# 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:

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

Start with the recommended first workflow:

```bash
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.

```bash
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.

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```text
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

```bash
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

![Terminal quick-scan placeholder](docs/images/terminal-quick-scan-placeholder.svg)

#### HTML evidence report

![HTML report placeholder](docs/images/html-report-placeholder.svg)

## Workspace Model

Sentra stores artifacts in the current workspace by default.

```text
.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:

```bash
python -m pytest -v
```

If Windows temp-directory permissions are noisy:

```bash
python -m pytest -v --basetemp .pytest_tmp
```

Verify entrypoints:

```bash
python -m sentra --help
sentra --help
```

Build artifacts locally:

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

## Documentation

- [Architecture](docs/architecture.md)
- [Capability Report](docs/capability-report.md)
- [Changelog](docs/changelog.md)
- [Release Notes Template](docs/release-notes.md)

