HomeSigSec

HomeSigSec is a reference implementation of a sensor-data monitoring pipeline. It collects wireless/RF observations, stores and normalizes them, derives detections, and makes results available for review or downstream notification.

The pipeline is intended to illustrate reusable stages and boundaries—not prescribe a particular home network, schedule, dashboard, alerting service, or deployment. Kismet is the current collection adapter; integrations and detection policies can be replaced to fit another environment.

Pipeline at a glance

1. Collect observations from one or more configured sources.
2. Normalize source records into a durable local data model while retaining a bounded raw-data window when needed for debugging.
3. Enrich and correlate observations with optional inventory or context sources.
4. Detect policy-relevant changes and maintain lifecycle state for findings.
5. Deliver notifications through a pluggable consumer; keep transport credentials and destinations outside the repository.
6. Retain and present data according to an explicit retention policy, with optional reporting or dashboards.

Operational collection and historical archiving are separate concerns: the operational path prioritizes fresh findings, while archive ingestion can run independently. A dashboard or notification consumer is optional and should not be required for collection or detection to continue.

Repository map

• scripts/ — collection, normalization, analysis, archive, and reporting entry points.
• assets/ — container and UI resources, public reference data, and an environment-variable template.
• references/ — general security guidance and upstream API notes suitable for the public project.
• tests/ — automated tests.
• output/ — local runtime state; ignored by Git.

Implementation-specific operational notes, runbooks, local schedules, and design drafts belong in local-only documentation and are excluded from version control. The scripts and configuration template are the source of truth for the current implementation.

Getting started

1. Install the runtime dependencies required by the components you plan to use.
2. Copy assets/.env.example to a local environment file and fill in only the settings needed for your deployment. Never commit real credentials, endpoints, network names, device identifiers, or runtime data.
3. Configure source adapters and policy inputs using local files outside version control.
4. Run the relevant collection/operational entry point, then optionally run archive ingestion, reporting, or notification consumers.
5. Review retention, access controls, and network exposure before enabling long-running services.

The example environment file contains placeholders. It is not a complete deployment recipe; source endpoints, credentials, schedules, storage locations, and integrations are deployment-specific.

Design principles

• Local-first: keep raw observations and sensitive identifiers in local runtime storage.
• Separation of concerns: collection, analysis, archive, notification, and presentation should fail independently where practical.
• Incremental and recoverable: record progress so interrupted jobs can resume safely and avoid duplicate processing.
• Least privilege: limit access to sensor APIs, local databases, and notification destinations.
• Configurable policy: keep approved inventories, watchlists, and environment-specific rules out of source control.
• Bounded sensitive data: document and enforce retention for raw observations and derived records.
• Evidence-based alerts: preserve enough provenance to explain a finding without unnecessarily copying raw data into notifications.

Security and privacy

Do not commit credentials, tokens, private endpoints, network or device identifiers, raw sensor data, local configuration, or operational logs. Runtime state and local implementation notes are excluded through .gitignore; verify the staged file list before every commit. Run a secret scanner before publishing changes.

See references/security-policy.md for the public security and privacy guidance. The Kismet API notes and probe/association guide are upstream-facing technical references, not deployment instructions.

Testing

Run the available automated tests with:

python3 -m unittest discover -s tests -v

Additional dependencies or integration services may be required for other checks. Do not run integration tests against production systems without explicit authorization.