inspectra-cli 2.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- inspectra/__init__.py +6 -0
- inspectra/__main__.py +6 -0
- inspectra/analysis/__init__.py +1 -0
- inspectra/analysis/recommendations.py +40 -0
- inspectra/analysis/risk.py +61 -0
- inspectra/baseline.py +94 -0
- inspectra/checks/__init__.py +79 -0
- inspectra/checks/context.py +29 -0
- inspectra/checks/directories.py +126 -0
- inspectra/checks/dns.py +141 -0
- inspectra/checks/fingerprint.py +102 -0
- inspectra/checks/headers.py +90 -0
- inspectra/checks/http.py +301 -0
- inspectra/checks/ports.py +179 -0
- inspectra/checks/robots.py +120 -0
- inspectra/checks/tls.py +212 -0
- inspectra/cli.py +413 -0
- inspectra/data/directory_wordlist.txt +170 -0
- inspectra/data/fingerprints.json +156 -0
- inspectra/data/header_rules.json +77 -0
- inspectra/models.py +138 -0
- inspectra/network.py +113 -0
- inspectra/orchestrator.py +145 -0
- inspectra/py.typed +0 -0
- inspectra/redact.py +92 -0
- inspectra/replay.py +195 -0
- inspectra/report/__init__.py +1 -0
- inspectra/report/html_report.py +69 -0
- inspectra/report/json_report.py +75 -0
- inspectra/report/markdown_report.py +86 -0
- inspectra/report/sarif_report.py +136 -0
- inspectra/report/templates/report.html.j2 +145 -0
- inspectra/safety.py +217 -0
- inspectra/utils.py +116 -0
- inspectra_cli-2.0.0.dist-info/METADATA +468 -0
- inspectra_cli-2.0.0.dist-info/RECORD +39 -0
- inspectra_cli-2.0.0.dist-info/WHEEL +4 -0
- inspectra_cli-2.0.0.dist-info/entry_points.txt +3 -0
- inspectra_cli-2.0.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,468 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: inspectra-cli
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: An open-source, explainable security assessment framework for safe and authorized security analysis.
|
|
5
|
+
Author: Inspectra contributors
|
|
6
|
+
License: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Keywords: cli,python,security,security-audit,vulnerability-assessment
|
|
9
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Intended Audience :: Information Technology
|
|
13
|
+
Classifier: Intended Audience :: System Administrators
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Classifier: Topic :: System :: Networking :: Monitoring
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: cryptography>=42.0
|
|
23
|
+
Requires-Dist: dnspython>=2.4.0
|
|
24
|
+
Requires-Dist: httpx>=0.27.0
|
|
25
|
+
Requires-Dist: jinja2>=3.1.0
|
|
26
|
+
Requires-Dist: python-nmap>=0.7.1
|
|
27
|
+
Requires-Dist: rich>=13.7.0
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: mypy>=1.8.0; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
|
|
31
|
+
Requires-Dist: pytest-httpserver>=1.0.0; extra == 'dev'
|
|
32
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
33
|
+
Requires-Dist: ruff>=0.2.0; extra == 'dev'
|
|
34
|
+
Description-Content-Type: text/markdown
|
|
35
|
+
|
|
36
|
+
<div align="center">
|
|
37
|
+
|
|
38
|
+
<img src="docs/assets/banner.png" alt="Inspectra banner" width="100%"/>
|
|
39
|
+
|
|
40
|
+
**An Open-Source Explainable Security Assessment Framework**
|
|
41
|
+
|
|
42
|
+
*Inspect. Observe. Assess. Explain. Report. **Never exploit.**.*
|
|
43
|
+
|
|
44
|
+
</div>
|
|
45
|
+
|
|
46
|
+
[](.github/workflows/ci.yml)
|
|
47
|
+
[](pyproject.toml)
|
|
48
|
+
[](LICENSE)
|
|
49
|
+
[](pyproject.toml)
|
|
50
|
+
[](pyproject.toml)
|
|
51
|
+
[](SECURITY.md)
|
|
52
|
+
[](https://shashu123456.github.io/Inspectra/)
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## ⚠️ Authorized Use Only
|
|
57
|
+
|
|
58
|
+
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.
|
|
59
|
+
|
|
60
|
+
**Scan only systems you own or are explicitly authorized to test** — unauthorized scanning may be illegal in your jurisdiction.
|
|
61
|
+
|
|
62
|
+
See [docs/safety.md](docs/safety.md) for the full ethics and legal guidance.
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## What Is Inspectra?
|
|
71
|
+
|
|
72
|
+
Inspectra is a single-command CLI tool that performs safe, passive security assessments on authorized targets and produces professional, **explainable** reports.
|
|
73
|
+
|
|
74
|
+
Most scanners dump raw technical output and leave you to interpret it. Inspectra is built around **explainability** — every finding answers:
|
|
75
|
+
|
|
76
|
+
| Question | Answer |
|
|
77
|
+
|----------|--------|
|
|
78
|
+
| **What was observed?** | The raw observation |
|
|
79
|
+
| **Why it matters** | The security reasoning, in plain language |
|
|
80
|
+
| **Evidence** | The data behind the observation |
|
|
81
|
+
| **Confidence** | How sure the tool is (low / medium / high) |
|
|
82
|
+
| **Severity** | Info / low / medium / high |
|
|
83
|
+
| **Recommendation** | A concrete next step |
|
|
84
|
+
|
|
85
|
+
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*.
|
|
86
|
+
|
|
87
|
+
**Built for:** students, junior security engineers, developers, small teams, home-lab users, and authorized training labs.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Why Inspectra Exists
|
|
92
|
+
|
|
93
|
+
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*.
|
|
94
|
+
|
|
95
|
+
Inspectra takes the opposite approach:
|
|
96
|
+
|
|
97
|
+
- **Explain first, raw data second.** Every finding explains itself.
|
|
98
|
+
- **One command, no server to run.** `inspectra scan example.com` is the whole workflow.
|
|
99
|
+
- **Reports are the deliverable.** JSON for tooling, Markdown for reading, self-contained HTML for sharing.
|
|
100
|
+
- **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.
|
|
101
|
+
|
|
102
|
+
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.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Key Features (v1.0.0)
|
|
107
|
+
|
|
108
|
+
- ✅ Target validation with normalization (domain, IP, URL)
|
|
109
|
+
- ✅ First-run authorization gate, persisted consent
|
|
110
|
+
- ✅ DNS resolution & record analysis (A/AAAA/CNAME/MX/NS/TXT)
|
|
111
|
+
- ✅ Port discovery via Nmap (top-1000 default, `--ports` / `--skip-ports`)
|
|
112
|
+
- ✅ HTTP analysis: redirects, error states, server disclosure
|
|
113
|
+
- ✅ TLS verification: expiry, self-signed, hostname mismatch, protocol versions
|
|
114
|
+
- ✅ Security header assessment (9 rules: HSTS, CSP, X-Frame-Options, …)
|
|
115
|
+
- ✅ Technology fingerprinting (24 curated signatures)
|
|
116
|
+
- ✅ robots.txt inspection (disallowed paths, sitemaps)
|
|
117
|
+
- ✅ Opt-in directory observation (rate-limited, GET-only, curated wordlist)
|
|
118
|
+
- ✅ Evidence capture on every finding
|
|
119
|
+
- ✅ Risk engine: severity × confidence → posture score & grade
|
|
120
|
+
- ✅ Reports: **Markdown** (default), **HTML** (self-contained, polished), **JSON**
|
|
121
|
+
- ✅ Exit codes for CI: 0 clean · 1 findings · 2 error
|
|
122
|
+
- ✅ All report timestamps displayed in **Indian Standard Time** (IST, UTC+05:30)
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Architecture
|
|
127
|
+
|
|
128
|
+
Inspectra is a linear pipeline with a check registry — deliberately simple.
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
CLI → Orchestrator → Checks → Risk Engine → Reporters
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
<details>
|
|
135
|
+
<summary><strong>View architecture diagram</strong></summary>
|
|
136
|
+
|
|
137
|
+
<img src="docs/assets/architecture.png" alt="Inspectra architecture diagram" width="100%"/>
|
|
138
|
+
|
|
139
|
+
</details>
|
|
140
|
+
|
|
141
|
+
**The layers:**
|
|
142
|
+
|
|
143
|
+
- **CLI** — `argparse` + Rich console. Parses arguments, shows the authorization gate, prints the summary, returns exit codes.
|
|
144
|
+
- **Orchestrator** — runs the registered checks in order with graceful degradation (one failed check never aborts the scan).
|
|
145
|
+
- **Checks** — eight independent modules sharing one data contract (`models.py`) and one `ScanContext` so later checks reuse earlier results instead of re-fetching.
|
|
146
|
+
- **Risk Engine** — applies the severity × confidence rubric and computes the posture score with letter grade.
|
|
147
|
+
- **Reporters** — three thin renderers (JSON, Markdown, self-contained HTML) over the same `ScanResult`.
|
|
148
|
+
|
|
149
|
+
The eight checks are: **dns · ports · http · tls · headers · fingerprint · robots · directories** (opt-in).
|
|
150
|
+
|
|
151
|
+
Adding a new check is one new file plus one registry line. See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Execution Flow
|
|
156
|
+
|
|
157
|
+
<details>
|
|
158
|
+
<summary><strong>View execution flow diagram</strong></summary>
|
|
159
|
+
|
|
160
|
+
<img src="docs/assets/workflow.png" alt="Inspectra execution flow diagram" width="100%"/>
|
|
161
|
+
|
|
162
|
+
</details>
|
|
163
|
+
|
|
164
|
+
1. **Validate** the target (domain, IP, or URL).
|
|
165
|
+
2. **Consent** — first-run authorization gate; remembered on disk; `--yes` skips the prompt.
|
|
166
|
+
3. Run checks in order: DNS → ports → HTTP → TLS → headers → fingerprint → robots → (directories, only if `--directories`).
|
|
167
|
+
4. Each check degrades gracefully. Only a fatal error (e.g. NXDOMAIN, Nmap missing) aborts the scan.
|
|
168
|
+
5. The risk engine scores findings by severity × confidence.
|
|
169
|
+
6. JSON (always) + Markdown or HTML reports are written; the console prints a summary.
|
|
170
|
+
7. Exit codes: `0` no actionable findings · `1` findings present · `2` error.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## Installation
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
pip install inspectra
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
From source:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
git clone https://github.com/shashu123456/Inspectra.git
|
|
184
|
+
cd Inspectra
|
|
185
|
+
python -m venv .venv
|
|
186
|
+
.venv\Scripts\activate # Windows
|
|
187
|
+
# source .venv/bin/activate # macOS / Linux
|
|
188
|
+
pip install -e ".[dev]"
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Installing Nmap (recommended)
|
|
192
|
+
|
|
193
|
+
Port discovery uses [Nmap](https://nmap.org). Without it, run with `--skip-ports`.
|
|
194
|
+
|
|
195
|
+
| OS | Command |
|
|
196
|
+
|----|---------|
|
|
197
|
+
| Debian/Ubuntu | `sudo apt install nmap` |
|
|
198
|
+
| Fedora | `sudo dnf install nmap` |
|
|
199
|
+
| macOS | `brew install nmap` |
|
|
200
|
+
| Windows | [nmap.org/download.html](https://nmap.org/download.html) (enable "Add to PATH") |
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Quick Start
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
inspectra scan example.com --format html
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
The first run shows the authorization agreement (accepted once, then remembered). Reports land in `./inspectra-report/`:
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
inspectra-report/
|
|
214
|
+
├── report.html (or report.md)
|
|
215
|
+
├── report.json
|
|
216
|
+
└── inspectra.log
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
All report timestamps are displayed in **Indian Standard Time** (`Asia/Kolkata`, UTC+05:30).
|
|
220
|
+
|
|
221
|
+
### Live Demo (no install needed to look around)
|
|
222
|
+
|
|
223
|
+
Run the included demo server locally:
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
.venv\Scripts\python demo\server.py
|
|
227
|
+
# then open http://127.0.0.1:9000/api/demo-page
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
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.
|
|
231
|
+
|
|
232
|
+
> The demo server and the static showcase in this README reflect the real tool — they are not mockups.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## CLI Examples
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
# Assess a website and get a polished HTML report
|
|
240
|
+
inspectra scan example.com --format html
|
|
241
|
+
|
|
242
|
+
# Assess a home-lab device with an explicit port list
|
|
243
|
+
inspectra scan 192.168.1.10:8443 --ports 80,443,8443
|
|
244
|
+
|
|
245
|
+
# Skip port discovery (no Nmap required)
|
|
246
|
+
inspheres scan example.com --skip-ports
|
|
247
|
+
|
|
248
|
+
# Opt-in directory observation with a custom wordlist
|
|
249
|
+
inspectra scan example.com --directories --directory-wordlist my-paths.txt
|
|
250
|
+
|
|
251
|
+
# Accept the authorization agreement without prompting (good for CI)
|
|
252
|
+
inspectra scan example.com --yes --format markdown
|
|
253
|
+
|
|
254
|
+
# Show the version
|
|
255
|
+
inspectra --version
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Example Console Output
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
$ inspectra scan example.com --yes --skip-ports --format html
|
|
262
|
+
Scan complete — example.com
|
|
263
|
+
┌───────────────┬───────┐
|
|
264
|
+
│ Severity │ Count │
|
|
265
|
+
├───────────────┼───────┤
|
|
266
|
+
│ HIGH │ 0 │
|
|
267
|
+
│ MEDIUM │ 4 │
|
|
268
|
+
│ LOW │ 4 │
|
|
269
|
+
│ INFO │ 5 │
|
|
270
|
+
│ Posture score │ 4.0 / 100 (F) │
|
|
271
|
+
└───────────────┴───────┘
|
|
272
|
+
Reports written to …/inspectra-report
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
(This is the committed sample output from a deliberately misconfigured fixture site — hence the F grade. See the [Sample Reports](#sample-reports) section.)
|
|
276
|
+
|
|
277
|
+
---
|
|
278
|
+
|
|
279
|
+
## Output Formats
|
|
280
|
+
|
|
281
|
+
### JSON
|
|
282
|
+
|
|
283
|
+
Always written. Machine-readable, stable schema, timezone-safe (`started_at` in UTC ISO-8601, `started_at_ist` for display).
|
|
284
|
+
|
|
285
|
+
### Markdown
|
|
286
|
+
|
|
287
|
+
Default human-readable format. Findings with severity headers, summary table, posture score, and scan metadata.
|
|
288
|
+
|
|
289
|
+
### HTML
|
|
290
|
+
|
|
291
|
+
Self-contained, polished report with inline CSS — no external assets, no network calls. Opens directly in any browser.
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## Screenshots
|
|
296
|
+
|
|
297
|
+
### CLI Demo
|
|
298
|
+
|
|
299
|
+
<img src="docs/assets/cli-demo.png" alt="Inspectra CLI demo" width="100%"/>
|
|
300
|
+
|
|
301
|
+
### Live Demo Page
|
|
302
|
+
|
|
303
|
+
<img src="docs/assets/dashboard-demo.png" alt="Inspectra live demo page" width="100%"/>
|
|
304
|
+
|
|
305
|
+
### Sample HTML Report
|
|
306
|
+
|
|
307
|
+
<img src="docs/assets/html-report.png" alt="Inspectra HTML report sample" width="100%"/>
|
|
308
|
+
|
|
309
|
+
### Sample Findings
|
|
310
|
+
|
|
311
|
+
<img src="docs/assets/findings.png" alt="Inspectra sample finding" width="100%"/>
|
|
312
|
+
|
|
313
|
+
### Report Summary
|
|
314
|
+
|
|
315
|
+
<img src="docs/assets/report-summary.png" alt="Inspectra report summary" width="100%"/>
|
|
316
|
+
|
|
317
|
+
---
|
|
318
|
+
|
|
319
|
+
## Sample Reports
|
|
320
|
+
|
|
321
|
+
Production-quality sample reports are committed under [`examples/sample-report/`](examples/sample-report/):
|
|
322
|
+
|
|
323
|
+
| File | Purpose |
|
|
324
|
+
|------|---------|
|
|
325
|
+
| [`report.md`](examples/sample-report/report.md) | Markdown report (default format) |
|
|
326
|
+
| [`report.html`](examples/sample-report/report.html) | Self-contained HTML report |
|
|
327
|
+
| [`report.json`](examples/sample-report/report.json) | Machine-readable JSON report |
|
|
328
|
+
|
|
329
|
+
A copy is also generated locally under [`sample-output/`](sample-output/) when you run the sample-report script.
|
|
330
|
+
|
|
331
|
+
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.
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## Project Logo
|
|
336
|
+
|
|
337
|
+
<div align="center">
|
|
338
|
+
|
|
339
|
+
<img src="docs/assets/logo.png" alt="Inspectra logo" width="320"/>
|
|
340
|
+
|
|
341
|
+
</div>
|
|
342
|
+
|
|
343
|
+
A scalable vector version is available at [`docs/assets/logo.svg`](docs/assets/logo.svg).
|
|
344
|
+
|
|
345
|
+
---
|
|
346
|
+
|
|
347
|
+
## Project Layout
|
|
348
|
+
|
|
349
|
+
```
|
|
350
|
+
Inspectra/
|
|
351
|
+
├── src/inspectra/ # the tool — one package, one responsibility per file
|
|
352
|
+
│ ├── cli.py # argparse, consent gate, exit codes
|
|
353
|
+
│ ├── orchestrator.py # runs checks, builds ScanResult
|
|
354
|
+
│ ├── models.py # Target / Finding / Severity / Confidence / ScanResult
|
|
355
|
+
│ ├── network.py # httpx client + TLS inspection
|
|
356
|
+
│ ├── checks/ # 8 assessment modules + registry
|
|
357
|
+
│ ├── analysis/ # risk engine + recommendation helpers
|
|
358
|
+
│ ├── report/ # json / markdown / html renderers
|
|
359
|
+
│ └── data/ # versioned rules, fingerprints, wordlist
|
|
360
|
+
├── tests/ # pytest suite (local fixture server, no internet)
|
|
361
|
+
├── demo/ # live demo: fixture site + in-browser scan UI
|
|
362
|
+
├── docs/ # architecture, usage, safety, roadmap
|
|
363
|
+
│ └── assets/ # logos, diagrams, screenshots
|
|
364
|
+
├── examples/sample-report/ # committed sample output (md + html + json)
|
|
365
|
+
├── sample-output/ # locally generated sample reports (gitignored)
|
|
366
|
+
└── scripts/ # report-regeneration helper
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
---
|
|
370
|
+
|
|
371
|
+
## Technologies
|
|
372
|
+
|
|
373
|
+
| Technology | Role |
|
|
374
|
+
|------------|------|
|
|
375
|
+
| [Python 3.11+](https://www.python.org/) | Runtime |
|
|
376
|
+
| [httpx](https://www.python-httpx.org/) | HTTP client — timeouts, redirect control |
|
|
377
|
+
| [dnspython](https://www.dnspython.org/) | DNS record resolution |
|
|
378
|
+
| [python-nmap](https://pypi.org/project/python-nmap/) | Nmap integration for port discovery |
|
|
379
|
+
| [cryptography](https://cryptography.io/) | X.509 certificate parsing |
|
|
380
|
+
| [rich](https://rich.readthedocs.io/) | Terminal UI — progress, colours, summary tables |
|
|
381
|
+
| [Jinja2](https://jinja.palletsprojects.com/) | HTML report templating |
|
|
382
|
+
| [pytest](https://pytest.org/) · [mypy](https://mypy.readthedocs.io/) · [ruff](https://ruff.rs/) | Tests, strict type checking, lint + format |
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## Quality
|
|
387
|
+
|
|
388
|
+
| Check | Result |
|
|
389
|
+
|-------|--------|
|
|
390
|
+
| Lint (ruff) | ✅ clean |
|
|
391
|
+
| Format (ruff) | ✅ clean |
|
|
392
|
+
| Type check (mypy) | ✅ strict, `src/` only |
|
|
393
|
+
| Tests (pytest) | ✅ 91 tests, ~90% coverage |
|
|
394
|
+
| CI | ✅ GitHub Actions on Python 3.11 / 3.12 |
|
|
395
|
+
|
|
396
|
+
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`).
|
|
397
|
+
|
|
398
|
+
---
|
|
399
|
+
|
|
400
|
+
## Documentation
|
|
401
|
+
|
|
402
|
+
| Document | Purpose |
|
|
403
|
+
|----------|---------|
|
|
404
|
+
| [docs/architecture.md](docs/architecture.md) | Single source of truth for the design |
|
|
405
|
+
| [docs/usage.md](docs/usage.md) | CLI reference, options, examples |
|
|
406
|
+
| [docs/safety.md](docs/safety.md) | Ethics, legal guidance, authorized-use checklist |
|
|
407
|
+
| [docs/roadmap.md](docs/roadmap.md) | Release history and future direction (planning only) |
|
|
408
|
+
| [CHANGELOG.md](CHANGELOG.md) | Notable changes per release |
|
|
409
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to add a check |
|
|
410
|
+
|
|
411
|
+
---
|
|
412
|
+
|
|
413
|
+
## Live Demo & Static Showcase
|
|
414
|
+
|
|
415
|
+
A live, interactive demo is built into the project:
|
|
416
|
+
|
|
417
|
+
- **Local demo server:** `.venv\Scripts\python demo\server.py` → `http://127.0.0.1:9000/api/demo-page`
|
|
418
|
+
- The demo page runs **real scans** against a harmless fixture site and renders findings in-browser.
|
|
419
|
+
|
|
420
|
+
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.
|
|
421
|
+
|
|
422
|
+
---
|
|
423
|
+
|
|
424
|
+
## Roadmap
|
|
425
|
+
|
|
426
|
+
V1 is feature-frozen by design. Every future idea lives in [`docs/roadmap.md`](docs/roadmap.md) — nothing from the roadmap is committed until it goes through a design review.
|
|
427
|
+
|
|
428
|
+
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.
|
|
429
|
+
|
|
430
|
+
The project's founding promise applies to every future version: **observe, assess, explain, report — never exploit.**
|
|
431
|
+
|
|
432
|
+
---
|
|
433
|
+
|
|
434
|
+
## Contributing
|
|
435
|
+
|
|
436
|
+
Contributions are welcome. The project follows one rule above all others:
|
|
437
|
+
|
|
438
|
+
> **Inspect. Observe. Assess. Explain. Report. Never exploit.**
|
|
439
|
+
|
|
440
|
+
Any contribution that adds exploitation, brute-forcing, payload delivery, or attack tooling will be declined, no matter how well implemented.
|
|
441
|
+
|
|
442
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide — including how to add a new check (it is deliberately small).
|
|
443
|
+
|
|
444
|
+
Use the issue templates for bug reports, feature requests, and new check proposals.
|
|
445
|
+
|
|
446
|
+
---
|
|
447
|
+
|
|
448
|
+
## Security Policy
|
|
449
|
+
|
|
450
|
+
If you discover a security vulnerability **in Inspectra itself**, please report it responsibly:
|
|
451
|
+
|
|
452
|
+
1. **Do not** open a public issue for security problems.
|
|
453
|
+
2. Use GitHub's **"Report a vulnerability"** (Security → Advisories) so the report stays private.
|
|
454
|
+
3. Include reproduction steps, affected version, and impact assessment.
|
|
455
|
+
|
|
456
|
+
See [SECURITY.md](SECURITY.md) for the full policy, supported versions, scope, and safe harbor statement.
|
|
457
|
+
|
|
458
|
+
---
|
|
459
|
+
|
|
460
|
+
## License
|
|
461
|
+
|
|
462
|
+
[MIT](LICENSE) — © 2026 Inspectra contributors.
|
|
463
|
+
|
|
464
|
+
---
|
|
465
|
+
|
|
466
|
+
## Disclaimer
|
|
467
|
+
|
|
468
|
+
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.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
inspectra/__init__.py,sha256=CDWu096l23o-CwSNvtFB85KVUlX1k11ZghBR9OYpmF4,162
|
|
2
|
+
inspectra/__main__.py,sha256=e6XaWHt1g6uWlEefrsdkCAhDkg6Wqyf87Jlg0RfZf04,127
|
|
3
|
+
inspectra/baseline.py,sha256=0dBgwEJrEQvJzsTUIlclSJFq0QAWOB0it8PVzp63d0k,3348
|
|
4
|
+
inspectra/cli.py,sha256=ovzWhVZ_bM4XtWe1pUnS_xZmqVdXkffmYuETE6LIrKc,14928
|
|
5
|
+
inspectra/models.py,sha256=gaki7McaCBBxnMt3srwWXTwfWOTiTnH_WgT5cMFDFio,3947
|
|
6
|
+
inspectra/network.py,sha256=JHW2XWSUM4Q3pPs1wL0mSDT4GCVfDrqhFnDW3YzBsIY,3683
|
|
7
|
+
inspectra/orchestrator.py,sha256=cwO25CeEWxXe3mKlDocz6tFZWnHaCQHGpZQ-NGE1zcI,6172
|
|
8
|
+
inspectra/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
inspectra/redact.py,sha256=X2xhlU_UnudGhFObtV2JGeQCrLomRJAtVk8z51ZXbDg,3242
|
|
10
|
+
inspectra/replay.py,sha256=KyBSYdnAaH1BXuig6YGuOFtjU_EshegV0sg-tvlXMq0,6265
|
|
11
|
+
inspectra/safety.py,sha256=0nCplTxdMYaR-JM0kdR2UF7dZbIDF8l-ifdkDpZS_DE,7230
|
|
12
|
+
inspectra/utils.py,sha256=M7ZqTchRqlvg8rCnhthDvOlbBJGIiZgl3ajtUJVHgs4,4028
|
|
13
|
+
inspectra/analysis/__init__.py,sha256=mx_R4_5m8bQtoB0miFu1Z3pBx6HKFrB0r1jJ6HDSgbE,65
|
|
14
|
+
inspectra/analysis/recommendations.py,sha256=LWeaSM4z4Ypo_fUDAIP1Z29slF1qmSzA7xKIuxT4wfg,1319
|
|
15
|
+
inspectra/analysis/risk.py,sha256=AnYPkGncv5JMVpWVedIp8joQV4M7eVQDGnCBV-luuSw,1836
|
|
16
|
+
inspectra/checks/__init__.py,sha256=CeaXV3VMZIXnKH95ukRniOQ6DQ2Xam0f80--ZShg4MM,2065
|
|
17
|
+
inspectra/checks/context.py,sha256=XVwVXuwNmxYvIdvu8noKYhrnlN-bh-rqJFThU-MLR2w,880
|
|
18
|
+
inspectra/checks/directories.py,sha256=2uaZBuIr9cmqRneJz9CI27TM-p0m8mNamYxqqAzP4a4,4434
|
|
19
|
+
inspectra/checks/dns.py,sha256=5GwVPbVMFg6nuHs_fv_EO0_ygfP64K-UgwX5RZgyIV0,5136
|
|
20
|
+
inspectra/checks/fingerprint.py,sha256=eM9YnmkzQUjAtEqJuGQk1cXBOhDOp7vEOETbyNgXjLo,3909
|
|
21
|
+
inspectra/checks/headers.py,sha256=lHE0FIDhAkPcqNmJS5l5Zy7cvZonWhTY2cUgi7BerTE,3333
|
|
22
|
+
inspectra/checks/http.py,sha256=Ograr1_SrkCLkN4v1IC56hggDhx8OsDCTQ6ASSAbr80,11569
|
|
23
|
+
inspectra/checks/ports.py,sha256=WLpjVnMmmJgeoVMWHHHmQ4BP2OZpucMmEOTbMGsW3nE,6365
|
|
24
|
+
inspectra/checks/robots.py,sha256=-QVerKFDncYw-e6b8FCwEmbKVJbT8t6MtMvQA7iC6Rs,4308
|
|
25
|
+
inspectra/checks/tls.py,sha256=UWaN1DM9lI-zV_WDGcj5Jkd3HLQeYiJVGOQK6CWVdPg,7946
|
|
26
|
+
inspectra/data/directory_wordlist.txt,sha256=EYq17smsphcpwAIiX_QPU2MwUzT_WwBqxaOSmfO6krQ,1952
|
|
27
|
+
inspectra/data/fingerprints.json,sha256=VxXxLY-Oel0vxzrCNjW6tAbiqpvfi7fKvtdLTAtLswU,4076
|
|
28
|
+
inspectra/data/header_rules.json,sha256=bR--zXfSeJRhxktd3SIrU_fle2zZiwPFLJE8rkrb8vk,3791
|
|
29
|
+
inspectra/report/__init__.py,sha256=BpnHqulHtLoqwTTnksK5PnKOxKLnZ3y0LKBg5Yb25Lo,68
|
|
30
|
+
inspectra/report/html_report.py,sha256=JB3h7OAQps57Uqxb_uPnE0-T4ajqjmPohIHWSBmoeBs,2036
|
|
31
|
+
inspectra/report/json_report.py,sha256=z9V5H8BbTcXKAeEf52k594jpbViZMkZNSUqPJS2OCY0,2521
|
|
32
|
+
inspectra/report/markdown_report.py,sha256=zmWNCvsl2s44L4ApiXU_in2EgadBWDr-qYD0kpor8jE,2906
|
|
33
|
+
inspectra/report/sarif_report.py,sha256=JxssoES57lsIGJgAYfJ8wjBuKV499Z-s7T7e9bsHHJM,4487
|
|
34
|
+
inspectra/report/templates/report.html.j2,sha256=QtQ7RRtKbUl17o9yNj28r9-s8lgxowZgRR1vSviZ6Mo,5563
|
|
35
|
+
inspectra_cli-2.0.0.dist-info/METADATA,sha256=qcEXOcIWTzl7kcerbMm_iqZK6d9pKiGb0azSrRtWl6M,18266
|
|
36
|
+
inspectra_cli-2.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
37
|
+
inspectra_cli-2.0.0.dist-info/entry_points.txt,sha256=o7ebqCtIvFPy5RwaMb7wkopl7e5fiFkP8y9o-zBU8cY,84
|
|
38
|
+
inspectra_cli-2.0.0.dist-info/licenses/LICENSE,sha256=_nuRvOzB1FUCDYAz7gf-C8mbPDdZFzEZiG3lUm_qCME,1078
|
|
39
|
+
inspectra_cli-2.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Inspectra contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and to sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
|
13
|
+
all copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
21
|
+
THE SOFTWARE.
|