sentra-iot 0.1.0

Defensive IoT evidence graph CLI for authorized security testing and operator-ready reporting.

Sentra

Sentra is a defensive IoT evidence graph CLI for authorized security testing, asset visibility, firmware inspection, and operator-ready reporting.

Sentra helps operators move from collection to correlation to prioritization without turning into an offensive framework or a heavyweight platform.

Why Sentra

Many IoT assessment tools fall into one of two camps:

• raw scanners that leave correlation and reporting to the operator
• large platforms that are harder to run, review, or share

Sentra is designed to sit in the middle:

• guided enough for fast first-run workflows
• structured enough for repeatable evidence handling
• explainable enough for reports, reviews, and lab use
• safe enough to stay focused on defensive discovery and analysis

Sentra does not include exploit execution, credential attacks, brute forcing, persistence, evasion, or destructive functionality.

Quick Start

Install for local development:

python -m pip install -e .[dev]
python -m sentra --help
sentra --help

Start with the recommended first workflow:

python -m sentra quick-scan --target 192.168.1.0/24 --yes

That guided flow:

1. discovers reachable devices and services
2. saves artifacts in the workspace
3. correlates evidence into the graph
4. generates a report

Recommended First Workflow

quick-scan is the default hero workflow and the best first command for most users.

python -m sentra quick-scan --target 192.168.1.0/24 --yes
python -m sentra quick-scan --target 10.0.0.15 --firmware-path ./firmware.zip --workspace ./lab --yes

Use it when you want a guided end-to-end run without stepping through each command manually.

Common Workflows

Step-by-step assessment

Use the explicit workflow when you want more control over collection and reporting stages.

python -m sentra scan net --target 192.168.1.0/24 --yes
python -m sentra scan firmware --path ./firmware.zip --workspace ./lab
python -m sentra correlate --workspace ./lab
python -m sentra report --workspace ./lab --format html

Firmware-only analysis

python -m sentra scan firmware --path ./firmware.zip --workspace ./lab
python -m sentra correlate --workspace ./lab
python -m sentra report --workspace ./lab --format markdown

Passive-summary intake

python -m sentra scan passive --summary-file ./captures/passive-summary.txt --workspace ./lab
python -m sentra correlate --workspace ./lab
python -m sentra report --workspace ./lab --format terminal

Reporting and review

python -m sentra report --workspace ./lab
python -m sentra report --workspace ./lab --format markdown --output ./reports/
python -m sentra report --workspace ./lab --format html --output ./reports/sentra-report.html
python -m sentra diff --before-workspace ./baseline --after-workspace ./lab --format html --output ./reports/

Workspace and intelligence checks

python -m sentra status --workspace ./lab
python -m sentra inspect-workspace --workspace ./lab
python -m sentra fingerprints validate --workspace ./lab
python -m sentra vulns inspect --workspace ./lab --json

CLI Reference

Root usage

sentra [OPTIONS] COMMAND [ARGS]...

Global options

• --workspace PATH: default workspace for Sentra artifacts
• --json: emit JSON to stdout by default
• --quiet: reduce terminal output
• --verbose: show extra terminal detail
• --version: show the installed Sentra version

Primary workflows

• quick-scan: recommended first assessment that scans, correlates, and reports in one guided pass
• scan net: discover reachable hosts, exposed services, and protocol clues from a host or CIDR target
• scan firmware: inspect a firmware image or archive for defensive evidence, findings, and software signals
• scan passive: parse an authorized passive-summary file into structured observations
• correlate: connect saved evidence into an explainable graph with ranked risk insights
• report: generate operator-facing terminal, Markdown, JSON, or HTML reports
• diff: compare two workspaces to highlight changed devices, findings, firmware signals, and correlations
• wizard: run the guided prompt-driven workflow for network or firmware assessments

Workspace and intelligence commands

• status: show what has been collected, analyzed, and reported in the current workspace
• inspect-workspace: inspect saved artifacts, report files, and firmware extraction directories
• fingerprints validate: validate built-in and custom fingerprint catalogs
• vulns inspect: inspect the offline vulnerability feed in a workspace

Useful command examples

python -m sentra --help
python -m sentra quick-scan --target 192.168.1.0/24 --yes
python -m sentra scan net --target 192.168.1.0/24 --yes
python -m sentra scan firmware --path ./firmware.zip --workspace ./lab
python -m sentra correlate --workspace ./lab
python -m sentra report --workspace ./lab --format html
python -m sentra diff --before-workspace ./baseline --after-workspace ./lab --format html
python -m sentra status --workspace ./lab
python -m sentra inspect-workspace --workspace ./lab
python -m sentra fingerprints validate --workspace ./lab
python -m sentra vulns inspect --workspace ./lab

Reports And Outputs

Sentra keeps machine-readable outputs deterministic while making human-facing outputs easier to review and share.

Terminal output

• guided summaries for scans, correlation, and reports
• top-risk context for devices and paths
• workspace-aware artifact visibility

Markdown output

• stable and review-friendly
• suitable for commit history, ticketing, and email review

JSON output

• deterministic and script-friendly
• suitable for automation and downstream processing

HTML output

• self-contained static report
• inline graph visualization
• structured sections for assets, findings, risky devices, risky paths, firmware evidence, and vulnerability intelligence

Report previews

Terminal quick-scan

HTML evidence report

Workspace Model

Sentra stores artifacts in the current workspace by default.

.sentra/
  network_scan.json
  passive_scan.json
  firmware_scan.json
  correlation.json
  report.md
  report.html
  cve_feed.json
  fingerprint_overrides.json

.sentra-fw/
  ...

sentra status gives a high-level summary of the workspace, and sentra inspect-workspace shows saved artifact and report paths more directly.

Safety And Scope

Sentra is built for:

• authorized security assessments
• asset visibility
• firmware inspection
• local lab research
• defensive enrichment, correlation, and reporting

Sentra is not built for:

• exploitation
• credential attacks
• brute forcing
• persistence
• evasion
• destructive activity

Advanced Notes

Fingerprint intelligence

The built-in fingerprint catalog is split into category files for maintainability and reviewability:

• cameras
• gateways
• general embedded systems
• industrial and OT classes
• NAS and storage classes
• printers
• routers
• smart plugs and relay-style devices

Sentra keeps compatibility with older simple override files while supporting richer matching concepts such as:

• aliases
• family
• class_context
• optional_indicators
• conflict_indicators
• evidence_groups

Merge behavior is deterministic:

1. built-in category files load first
2. workspace overrides replace matching built-in names
3. explicit user override files take highest precedence
4. ranking uses evidence quality, specificity, confidence, and source precedence

Validation and packaging

Run tests:

python -m pytest -v

If Windows temp-directory permissions are noisy:

python -m pytest -v --basetemp .pytest_tmp

Verify entrypoints:

python -m sentra --help
sentra --help

Build artifacts locally:

python -m pip install -e .[dev]
python -m build
python -m twine check dist/*

Documentation

• Architecture
• Capability Report
• Changelog
• Release Notes Template