An Open-Source Explainable Security Assessment Framework
Inspect. Observe. Assess. Explain. Report. Never exploit..
⚠️ Authorized Use Only
Inspectra is a passive assessment tool. It observes what a system willingly reveals and explains what it means. It never exploits, never brute-forces, and never sends attack payloads.
Scan only systems you own or are explicitly authorized to test — unauthorized scanning may be illegal in your jurisdiction.
See docs/safety.md for the full ethics and legal guidance.
This is inspectra-cli. An unrelated package named inspectra exists on PyPI (an AI code-review tool). Installing this project provides the inspectra and inspectra-cli commands.
What Is Inspectra?
Inspectra is a single-command CLI tool that performs safe, passive security assessments on authorized targets and produces professional, explainable reports.
Most scanners dump raw technical output and leave you to interpret it. Inspectra is built around explainability — every finding answers:
| Question | Answer |
|---|---|
| What was observed? | The raw observation |
| Why it matters | The security reasoning, in plain language |
| Evidence | The data behind the observation |
| Confidence | How sure the tool is (low / medium / high) |
| Severity | Info / low / medium / high |
| Recommendation | A concrete next step |
On top of that, Inspectra computes a posture score (0–100 with a letter grade) so you can measure improvement: scan → fix → re-scan → watch the score rise.
Built for: students, junior security engineers, developers, small teams, home-lab users, and authorized training labs.
Why Inspectra Exists
Security tooling is full of noise. A scan can return hundreds of lines of raw output and still tell you nothing about what you should actually do.
Inspectra takes the opposite approach:
- Explain first, raw data second. Every finding explains itself.
- One command, no server to run.
inspectra scan example.comis the whole workflow. - Reports are the deliverable. JSON for tooling, Markdown for reading, self-contained HTML for sharing.
- Safe by design. GET-only requests, timeouts everywhere, rate-limited opt-in directory checks, first-run authorization gate. No exploitation code anywhere in the codebase.
It is intentionally not an offensive tool, a brute-forcer, or a vulnerability database. It assesses what a target willingly exposes and explains what that means.
Key Features (v1.0.0)
- ✅ Target validation with normalization (domain, IP, URL)
- ✅ First-run authorization gate, persisted consent
- ✅ DNS resolution & record analysis (A/AAAA/CNAME/MX/NS/TXT)
- ✅ Port discovery via Nmap (top-1000 default,
--ports/--skip-ports) - ✅ HTTP analysis: redirects, error states, server disclosure
- ✅ TLS verification: expiry, self-signed, hostname mismatch, protocol versions
- ✅ Security header assessment (9 rules: HSTS, CSP, X-Frame-Options, …)
- ✅ Technology fingerprinting (24 curated signatures)
- ✅ robots.txt inspection (disallowed paths, sitemaps)
- ✅ Opt-in directory observation (rate-limited, GET-only, curated wordlist)
- ✅ Evidence capture on every finding
- ✅ Risk engine: severity × confidence → posture score & grade
- ✅ Reports: Markdown (default), HTML (self-contained, polished), JSON
- ✅ Exit codes for CI: 0 clean · 1 findings · 2 error
- ✅ All report timestamps displayed in Indian Standard Time (IST, UTC+05:30)
Architecture
Inspectra is a linear pipeline with a check registry — deliberately simple.
CLI → Orchestrator → Checks → Risk Engine → Reporters
View architecture diagram
The layers:
- CLI —
argparse+ Rich console. Parses arguments, shows the authorization gate, prints the summary, returns exit codes. - Orchestrator — runs the registered checks in order with graceful degradation (one failed check never aborts the scan).
- Checks — eight independent modules sharing one data contract (
models.py) and oneScanContextso later checks reuse earlier results instead of re-fetching. - Risk Engine — applies the severity × confidence rubric and computes the posture score with letter grade.
- Reporters — three thin renderers (JSON, Markdown, self-contained HTML) over the same
ScanResult.
The eight checks are: dns · ports · http · tls · headers · fingerprint · robots · directories (opt-in).
Adding a new check is one new file plus one registry line. See CONTRIBUTING.md.
Execution Flow
View execution flow diagram
- Validate the target (domain, IP, or URL).
- Consent — first-run authorization gate; remembered on disk;
--yesskips the prompt. - Run checks in order: DNS → ports → HTTP → TLS → headers → fingerprint → robots → (directories, only if
--directories). - Each check degrades gracefully. Only a fatal error (e.g. NXDOMAIN, Nmap missing) aborts the scan.
- The risk engine scores findings by severity × confidence.
- JSON (always) + Markdown or HTML reports are written; the console prints a summary.
- Exit codes:
0no actionable findings ·1findings present ·2error.
Installation
pip install inspectra
From source:
git clone https://github.com/shashu123456/Inspectra.git
cd Inspectra
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS / Linux
pip install -e ".[dev]"
Installing Nmap (recommended)
Port discovery uses Nmap. Without it, run with --skip-ports.
| OS | Command |
|---|---|
| Debian/Ubuntu | sudo apt install nmap |
| Fedora | sudo dnf install nmap |
| macOS | brew install nmap |
| Windows | nmap.org/download.html (enable "Add to PATH") |
Quick Start
inspectra scan example.com --format html
The first run shows the authorization agreement (accepted once, then remembered). Reports land in ./inspectra-report/:
inspectra-report/
├── report.html (or report.md)
├── report.json
└── inspectra.log
All report timestamps are displayed in Indian Standard Time (Asia/Kolkata, UTC+05:30).
Live Demo (no install needed to look around)
Run the included demo server locally:
.venv\Scripts\python demo\server.py
# then open http://127.0.0.1:9000/api/demo-page
The demo hosts a harmless, deliberately misconfigured fixture site and a page that runs real Inspectra scans against it, rendering findings in-browser with links to the full HTML/Markdown/JSON reports.
The demo server and the static showcase in this README reflect the real tool — they are not mockups.
CLI Examples
# Assess a website and get a polished HTML report
inspectra scan example.com --format html
# Assess a home-lab device with an explicit port list
inspectra scan 192.168.1.10:8443 --ports 80,443,8443
# Skip port discovery (no Nmap required)
inspheres scan example.com --skip-ports
# Opt-in directory observation with a custom wordlist
inspectra scan example.com --directories --directory-wordlist my-paths.txt
# Accept the authorization agreement without prompting (good for CI)
inspectra scan example.com --yes --format markdown
# Show the version
inspectra --version
Example Console Output
$ inspectra scan example.com --yes --skip-ports --format html
Scan complete — example.com
┌───────────────┬───────┐
│ Severity │ Count │
├───────────────┼───────┤
│ HIGH │ 0 │
│ MEDIUM │ 4 │
│ LOW │ 4 │
│ INFO │ 5 │
│ Posture score │ 4.0 / 100 (F) │
└───────────────┴───────┘
Reports written to …/inspectra-report
(This is the committed sample output from a deliberately misconfigured fixture site — hence the F grade. See the Sample Reports section.)
Output Formats
JSON
Always written. Machine-readable, stable schema, timezone-safe (started_at in UTC ISO-8601, started_at_ist for display).
Markdown
Default human-readable format. Findings with severity headers, summary table, posture score, and scan metadata.
HTML
Self-contained, polished report with inline CSS — no external assets, no network calls. Opens directly in any browser.
Screenshots
CLI Demo
Live Demo Page
Sample HTML Report
Sample Findings
Report Summary
Sample Reports
Production-quality sample reports are committed under examples/sample-report/:
| File | Purpose |
|---|---|
report.md |
Markdown report (default format) |
report.html |
Self-contained HTML report |
report.json |
Machine-readable JSON report |
A copy is also generated locally under sample-output/ when you run the sample-report script.
The sample target is a deliberately misconfigured fixture site — the posture score is a low 4.0 / 100 (F) by design, so the reports demonstrate how Inspectra surfaces real issues.
Project Logo
A scalable vector version is available at docs/assets/logo.svg.
Project Layout
Inspectra/
├── src/inspectra/ # the tool — one package, one responsibility per file
│ ├── cli.py # argparse, consent gate, exit codes
│ ├── orchestrator.py # runs checks, builds ScanResult
│ ├── models.py # Target / Finding / Severity / Confidence / ScanResult
│ ├── network.py # httpx client + TLS inspection
│ ├── checks/ # 8 assessment modules + registry
│ ├── analysis/ # risk engine + recommendation helpers
│ ├── report/ # json / markdown / html renderers
│ └── data/ # versioned rules, fingerprints, wordlist
├── tests/ # pytest suite (local fixture server, no internet)
├── demo/ # live demo: fixture site + in-browser scan UI
├── docs/ # architecture, usage, safety, roadmap
│ └── assets/ # logos, diagrams, screenshots
├── examples/sample-report/ # committed sample output (md + html + json)
├── sample-output/ # locally generated sample reports (gitignored)
└── scripts/ # report-regeneration helper
Technologies
| Technology | Role |
|---|---|
| Python 3.11+ | Runtime |
| httpx | HTTP client — timeouts, redirect control |
| dnspython | DNS record resolution |
| python-nmap | Nmap integration for port discovery |
| cryptography | X.509 certificate parsing |
| rich | Terminal UI — progress, colours, summary tables |
| Jinja2 | HTML report templating |
| pytest · mypy · ruff | Tests, strict type checking, lint + format |
Quality
| Check | Result |
|---|---|
| Lint (ruff) | ✅ clean |
| Format (ruff) | ✅ clean |
| Type check (mypy) | ✅ strict, src/ only |
| Tests (pytest) | ✅ 91 tests, ~90% coverage |
| CI | ✅ GitHub Actions on Python 3.11 / 3.12 |
The test suite runs against a local fixture server — it never touches the internet. Nmap is not required for tests or the demo (--skip-ports).
Documentation
| Document | Purpose |
|---|---|
| docs/architecture.md | Single source of truth for the design |
| docs/usage.md | CLI reference, options, examples |
| docs/safety.md | Ethics, legal guidance, authorized-use checklist |
| docs/roadmap.md | Release history and future direction (planning only) |
| CHANGELOG.md | Notable changes per release |
| CONTRIBUTING.md | How to add a check |
Live Demo & Static Showcase
A live, interactive demo is built into the project:
- Local demo server:
.venv\Scripts\python demo\server.py→http://127.0.0.1:9000/api/demo-page - The demo page runs real scans against a harmless fixture site and renders findings in-browser.
To make the project browsable without installing anything, this repository also ships a static showcase rendered directly from the real tool's output. The diagrams, screenshots, and sample reports in this README are generated from the actual code — they are not mockups.
Roadmap
V1 is feature-frozen by design. Every future idea lives in docs/roadmap.md — nothing from the roadmap is committed until it goes through a design review.
V2 candidates include: an async engine, a plugin system for third-party checks, cookie/CORS audits, passive subdomain enumeration via certificate transparency, and a read-only web dashboard over the existing report.json schema.
The project's founding promise applies to every future version: observe, assess, explain, report — never exploit.
Contributing
Contributions are welcome. The project follows one rule above all others:
Inspect. Observe. Assess. Explain. Report. Never exploit.
Any contribution that adds exploitation, brute-forcing, payload delivery, or attack tooling will be declined, no matter how well implemented.
See CONTRIBUTING.md for the full guide — including how to add a new check (it is deliberately small).
Use the issue templates for bug reports, feature requests, and new check proposals.
Security Policy
If you discover a security vulnerability in Inspectra itself, please report it responsibly:
- Do not open a public issue for security problems.
- Use GitHub's "Report a vulnerability" (Security → Advisories) so the report stays private.
- Include reproduction steps, affected version, and impact assessment.
See SECURITY.md for the full policy, supported versions, scope, and safe harbor statement.
License
MIT — © 2026 Inspectra contributors.
Disclaimer
Inspectra is provided "as is", without warranty of any kind. You are solely responsible for ensuring your use of the tool is legal and authorized. The authors and contributors are not liable for misuse.
Metadata
Release files for inspectra-cli 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| inspectra_cli-2.0.0.tar.gz | 932.5 kB | With provenance | Details for inspectra_cli-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| inspectra_cli-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for inspectra_cli-2.0.0-py3-none-any.whl |
Total release size: 992.9 kB
Release files / inspectra_cli-2.0.0.tar.gz
| Download URL | inspectra_cli-2.0.0.tar.gz |
|---|---|
| Size | 932.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0cc3184d70df8c0665c16ab54b257bc9880ca370f7e9b30a6482e0cf801d432
|
|
BLAKE2b-256 checksum How to use checksums |
42b612ae1c49a774e33773960d379371effa5f1f8b32212ecc36648e2b7c4bb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / inspectra_cli-2.0.0-py3-none-any.whl
| Download URL | inspectra_cli-2.0.0-py3-none-any.whl |
|---|---|
| Size | 60.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8e632f43e8f27784164286ba0546e57aff41947068e68df78f1b274d2e2379c3
|
|
BLAKE2b-256 checksum How to use checksums |
b16d2b1f06277522c6b4ffe01069e2af87622061c8ac64ff99e1f6a353bcf3b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for inspectra-cli 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for inspectra_cli-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.