UserAlternately/rf-sentinel

📡 RF SENTINEL v15 — Dual-AI RF Monitoring (Receive-Only)

Hệ thống giám sát phổ vô tuyến THỤ ĐỘNG (receive-only) với Dual-AI classification + Confidence Gating, dành cho mục đích nghiên cứu, giám sát an toàn tần số nội bộ hợp pháp và thực thi pháp luật được ủy quyền.

⚖️ BẮT BUỘC ĐỌC: LAW_DISCLAIMER.md trước khi sử dụng. Công cụ chỉ THU, không PHÁT bất kỳ tín hiệu nào.

⚠️ File engine rf_sentinel.py (bản v15_gated của bạn) KHÔNG có trong repo này — hãy copy file engine của bạn vào thư mục gốc cạnh dashboard_api.py. Xem mục Cấu trúc package.

Cấu trúc package

File	Vai trò
rf_sentinel.py	Engine gốc (của bạn) — Dual-AI engine, DB, repository functions repo_get_*. Copy vào đây.
dashboard_api.py	Web Dashboard API (FastAPI) — tái dùng trực tiếp repo_get_alerts, repo_get_noisiest_channels, repo_get_stats_summary, repo_get_channel_spectrum_history. Không viết lại SQL (single source of truth).
webui/index.html	Frontend Vue 3 qua CDN (không cần Node.js/build). Alerts + Top kênh ồn + biểu đồ lịch sử phổ (Chart.js).
streamlit_dashboard.py	Phương án thay thế nhẹ (Streamlit), phù hợp Raspberry Pi thực địa.
verify_integrity.py	Anti-tamper / chain-of-custody: SHA-256 manifest, hỗ trợ HMAC-SHA256.
LAW_DISCLAIMER.md	Tuyên bố pháp lý: receive-only, phạm vi cho phép/cấm, chain-of-custody.
LICENSE.md	AGPL-3.0-or-later + ghi chú dual-licensing.
requirements.txt	Dependencies cho ENGINE (SDR/DSP: numpy, scipy, hmmlearn, pyhackrf...).
requirements-dashboard.txt	Dependencies cho DASHBOARD (nhẹ, không cần SDR).

Quick start — Dashboard (FastAPI + Vue)

# 1. Copy file engine rf_sentinel.py của bạn vào thư mục gốc của package
# 2. Cài dependencies (máy dashboard KHÔNG cần cắm HackRF):
pip install -r requirements-dashboard.txt

# 3. Cấu hình auth (BẮT BUỘC — dashboard từ chối chạy nếu thiếu mật khẩu):
export DASH_USER=officer
export DASH_PASS="<mat-khau-manh-that>"

# 4. Chạy:
python dashboard_api.py
# Mở http://127.0.0.1:8000/ — trình duyệt sẽ hiện hộp thoại đăng nhập

Phương án Streamlit (MVP nhanh, chạy tốt trên Raspberry Pi):

streamlit run streamlit_dashboard.py

Deploy production (systemd + Nginx HTTPS)

1. Chạy engine như service (/etc/systemd/system/rf-sentinel.service):

[Unit]
Description=RF Sentinel Engine (receive-only RF monitoring)
After=network.target

[Service]
Type=simple
User=rfops
WorkingDirectory=/opt/rf-sentinel
ExecStart=/usr/bin/python3 /opt/rf-sentinel/rf_sentinel.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload && sudo systemctl enable --now rf-sentinel

2. Chạy dashboard như service (rf-sentinel-dashboard.service, tương tự): ExecStart=/usr/bin/python3 /opt/rf-sentinel/dashboard_api.py với Environment=DASH_USER=..., Environment=DASH_PASS=... trong mục [Service].

3. Nginx reverse-proxy HTTPS bắt buộc (Basic Auth qua HTTP thuần KHÔNG an toàn):

server {
    listen 443 ssl;
    server_name rf-sentinel.example.gov;
    ssl_certificate     /etc/ssl/rf-sentinel.crt;
    ssl_certificate_key /etc/ssl/rf-sentinel.key;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

SQLite concurrent access (engine ghi + dashboard đọc)

Đảm bảo init_db() trong engine có 2 dòng này để 2 tiến trình không khoá bảng lẫn nhau:

conn.execute("PRAGMA journal_mode=WAL")
conn.execute("PRAGMA synchronous=NORMAL")

Chain-of-custody / Anti-tamper

python verify_integrity.py --generate                # tao MANIFEST.sha256 sau khi deploy/calibrate
python verify_integrity.py --generate --key k.bin    # ky HMAC-SHA256 (manh hon)
python verify_integrity.py --verify                  # kiem tra truoc moi lan dung/chuyen giao bang chứng

Giữ MANIFEST.sha256 (và key file) ở nơi riêng với dữ liệu bằng chứng. Bất kỳ MODIFIED nào phải được giải trình trước khi dữ liệu dùng làm chứng cứ.

Release strategy (tạo download link thật của bạn)

git init && git add . && git commit -m "RF Sentinel v15.0.0"
git tag v15.0.0 && git remote add origin git@github.com:<org>/rf-sentinel.git
git push origin main --tags
# -> GitHub Releases: https://github.com/<org>/rf-sentinel/releases/download/v15.0.0/rf-sentinel-v15.zip

Hoặc Docker: build image rồi docker push ghcr.io/<org>/rf-sentinel:15.0.0.

License

AGPL-3.0-or-later — xem LICENSE.md. Dual-licensing thương mại: liên hệ author.