inspectra-cli 2.0.0__tar.gz

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.
Files changed (134) hide show
  1. inspectra_cli-2.0.0/.dockerignore +18 -0
  2. inspectra_cli-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md +30 -0
  3. inspectra_cli-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md +21 -0
  4. inspectra_cli-2.0.0/.github/ISSUE_TEMPLATE/new_check.md +24 -0
  5. inspectra_cli-2.0.0/.github/workflows/ci.yml +41 -0
  6. inspectra_cli-2.0.0/.github/workflows/docker.yml +45 -0
  7. inspectra_cli-2.0.0/.github/workflows/pages.yml +37 -0
  8. inspectra_cli-2.0.0/.github/workflows/release.yml +34 -0
  9. inspectra_cli-2.0.0/.gitignore +36 -0
  10. inspectra_cli-2.0.0/CHANGELOG.md +77 -0
  11. inspectra_cli-2.0.0/CODE_OF_CONDUCT.md +63 -0
  12. inspectra_cli-2.0.0/CONTRIBUTING.md +86 -0
  13. inspectra_cli-2.0.0/Dockerfile +21 -0
  14. inspectra_cli-2.0.0/LICENSE +21 -0
  15. inspectra_cli-2.0.0/PKG-INFO +468 -0
  16. inspectra_cli-2.0.0/PUBLISH-TESTPYPI.bat +6 -0
  17. inspectra_cli-2.0.0/README.md +433 -0
  18. inspectra_cli-2.0.0/RELEASE_NOTES.md +52 -0
  19. inspectra_cli-2.0.0/SECURITY.md +33 -0
  20. inspectra_cli-2.0.0/action.yml +32 -0
  21. inspectra_cli-2.0.0/demo/index.html +207 -0
  22. inspectra_cli-2.0.0/demo/server.py +168 -0
  23. inspectra_cli-2.0.0/docs/architecture.md +136 -0
  24. inspectra_cli-2.0.0/docs/assets/architecture.png +0 -0
  25. inspectra_cli-2.0.0/docs/assets/banner.png +0 -0
  26. inspectra_cli-2.0.0/docs/assets/cli-demo.png +0 -0
  27. inspectra_cli-2.0.0/docs/assets/dashboard-demo.png +0 -0
  28. inspectra_cli-2.0.0/docs/assets/findings.png +0 -0
  29. inspectra_cli-2.0.0/docs/assets/html-report.png +0 -0
  30. inspectra_cli-2.0.0/docs/assets/logo.png +0 -0
  31. inspectra_cli-2.0.0/docs/assets/logo.svg +43 -0
  32. inspectra_cli-2.0.0/docs/assets/report-summary.png +0 -0
  33. inspectra_cli-2.0.0/docs/assets/workflow.png +0 -0
  34. inspectra_cli-2.0.0/docs/benchmark.md +95 -0
  35. inspectra_cli-2.0.0/docs/roadmap.md +62 -0
  36. inspectra_cli-2.0.0/docs/safety.md +65 -0
  37. inspectra_cli-2.0.0/docs/usage.md +199 -0
  38. inspectra_cli-2.0.0/examples/sample-report/report.html +261 -0
  39. inspectra_cli-2.0.0/examples/sample-report/report.json +192 -0
  40. inspectra_cli-2.0.0/examples/sample-report/report.md +156 -0
  41. inspectra_cli-2.0.0/lab/docker-compose.yml +127 -0
  42. inspectra_cli-2.0.0/lab/expected.json +62 -0
  43. inspectra_cli-2.0.0/lab/results/benchmark_results.json +193 -0
  44. inspectra_cli-2.0.0/lab/results/target1.json +69 -0
  45. inspectra_cli-2.0.0/lab/results/target10.json +175 -0
  46. inspectra_cli-2.0.0/lab/results/target11.json +159 -0
  47. inspectra_cli-2.0.0/lab/results/target12.json +159 -0
  48. inspectra_cli-2.0.0/lab/results/target2.json +69 -0
  49. inspectra_cli-2.0.0/lab/results/target3.json +69 -0
  50. inspectra_cli-2.0.0/lab/results/target4.json +39 -0
  51. inspectra_cli-2.0.0/lab/results/target5.json +39 -0
  52. inspectra_cli-2.0.0/lab/results/target6.json +174 -0
  53. inspectra_cli-2.0.0/lab/results/target7.json +189 -0
  54. inspectra_cli-2.0.0/lab/results/target8.json +189 -0
  55. inspectra_cli-2.0.0/lab/results/target9.json +159 -0
  56. inspectra_cli-2.0.0/lab/targets/target1/server.py +33 -0
  57. inspectra_cli-2.0.0/lab/targets/target10/server.py +33 -0
  58. inspectra_cli-2.0.0/lab/targets/target11/server.py +31 -0
  59. inspectra_cli-2.0.0/lab/targets/target12/server.py +40 -0
  60. inspectra_cli-2.0.0/lab/targets/target2/server.py +33 -0
  61. inspectra_cli-2.0.0/lab/targets/target3/server.py +33 -0
  62. inspectra_cli-2.0.0/lab/targets/target4/server.py +59 -0
  63. inspectra_cli-2.0.0/lab/targets/target5/server.py +60 -0
  64. inspectra_cli-2.0.0/lab/targets/target6/server.py +27 -0
  65. inspectra_cli-2.0.0/lab/targets/target7/server.py +24 -0
  66. inspectra_cli-2.0.0/lab/targets/target8/server.py +41 -0
  67. inspectra_cli-2.0.0/lab/targets/target9/server.py +49 -0
  68. inspectra_cli-2.0.0/pyproject.toml +81 -0
  69. inspectra_cli-2.0.0/run_benchmark.py +126 -0
  70. inspectra_cli-2.0.0/scripts/benchmark.py +266 -0
  71. inspectra_cli-2.0.0/scripts/generate_sample_report.py +59 -0
  72. inspectra_cli-2.0.0/scripts/publish-testpypi.ps1 +205 -0
  73. inspectra_cli-2.0.0/site/.nojekyll +0 -0
  74. inspectra_cli-2.0.0/site/index.html +35 -0
  75. inspectra_cli-2.0.0/site/report.html +261 -0
  76. inspectra_cli-2.0.0/site/report.json +192 -0
  77. inspectra_cli-2.0.0/site/report.md +156 -0
  78. inspectra_cli-2.0.0/src/inspectra/__init__.py +6 -0
  79. inspectra_cli-2.0.0/src/inspectra/__main__.py +6 -0
  80. inspectra_cli-2.0.0/src/inspectra/analysis/__init__.py +1 -0
  81. inspectra_cli-2.0.0/src/inspectra/analysis/recommendations.py +40 -0
  82. inspectra_cli-2.0.0/src/inspectra/analysis/risk.py +61 -0
  83. inspectra_cli-2.0.0/src/inspectra/baseline.py +94 -0
  84. inspectra_cli-2.0.0/src/inspectra/checks/__init__.py +79 -0
  85. inspectra_cli-2.0.0/src/inspectra/checks/context.py +29 -0
  86. inspectra_cli-2.0.0/src/inspectra/checks/directories.py +126 -0
  87. inspectra_cli-2.0.0/src/inspectra/checks/dns.py +141 -0
  88. inspectra_cli-2.0.0/src/inspectra/checks/fingerprint.py +102 -0
  89. inspectra_cli-2.0.0/src/inspectra/checks/headers.py +90 -0
  90. inspectra_cli-2.0.0/src/inspectra/checks/http.py +301 -0
  91. inspectra_cli-2.0.0/src/inspectra/checks/ports.py +179 -0
  92. inspectra_cli-2.0.0/src/inspectra/checks/robots.py +120 -0
  93. inspectra_cli-2.0.0/src/inspectra/checks/tls.py +212 -0
  94. inspectra_cli-2.0.0/src/inspectra/cli.py +413 -0
  95. inspectra_cli-2.0.0/src/inspectra/data/directory_wordlist.txt +170 -0
  96. inspectra_cli-2.0.0/src/inspectra/data/fingerprints.json +156 -0
  97. inspectra_cli-2.0.0/src/inspectra/data/header_rules.json +77 -0
  98. inspectra_cli-2.0.0/src/inspectra/models.py +138 -0
  99. inspectra_cli-2.0.0/src/inspectra/network.py +113 -0
  100. inspectra_cli-2.0.0/src/inspectra/orchestrator.py +145 -0
  101. inspectra_cli-2.0.0/src/inspectra/py.typed +0 -0
  102. inspectra_cli-2.0.0/src/inspectra/redact.py +92 -0
  103. inspectra_cli-2.0.0/src/inspectra/replay.py +195 -0
  104. inspectra_cli-2.0.0/src/inspectra/report/__init__.py +1 -0
  105. inspectra_cli-2.0.0/src/inspectra/report/html_report.py +69 -0
  106. inspectra_cli-2.0.0/src/inspectra/report/json_report.py +75 -0
  107. inspectra_cli-2.0.0/src/inspectra/report/markdown_report.py +86 -0
  108. inspectra_cli-2.0.0/src/inspectra/report/sarif_report.py +136 -0
  109. inspectra_cli-2.0.0/src/inspectra/report/templates/report.html.j2 +145 -0
  110. inspectra_cli-2.0.0/src/inspectra/safety.py +217 -0
  111. inspectra_cli-2.0.0/src/inspectra/utils.py +116 -0
  112. inspectra_cli-2.0.0/tests/conftest.py +80 -0
  113. inspectra_cli-2.0.0/tests/fixtures/replay/107b5723ce35838ea43887ffc9376a0ec84f2fe57bdd5f9a7f125061ccf63ecc.json +16 -0
  114. inspectra_cli-2.0.0/tests/fixtures/replay/60e8ee63d1b6b15b2ae35f9f6f5bd15eebbede57e329131f98d28edae4dfd34d.json +16 -0
  115. inspectra_cli-2.0.0/tests/fixtures/replay/index.json +12 -0
  116. inspectra_cli-2.0.0/tests/test_benchmark_spec.py +67 -0
  117. inspectra_cli-2.0.0/tests/test_cli.py +403 -0
  118. inspectra_cli-2.0.0/tests/test_directories.py +55 -0
  119. inspectra_cli-2.0.0/tests/test_dns.py +73 -0
  120. inspectra_cli-2.0.0/tests/test_fingerprint.py +51 -0
  121. inspectra_cli-2.0.0/tests/test_headers.py +67 -0
  122. inspectra_cli-2.0.0/tests/test_http.py +159 -0
  123. inspectra_cli-2.0.0/tests/test_models.py +61 -0
  124. inspectra_cli-2.0.0/tests/test_orchestrator.py +55 -0
  125. inspectra_cli-2.0.0/tests/test_ports.py +96 -0
  126. inspectra_cli-2.0.0/tests/test_redact.py +112 -0
  127. inspectra_cli-2.0.0/tests/test_replay.py +365 -0
  128. inspectra_cli-2.0.0/tests/test_reports.py +99 -0
  129. inspectra_cli-2.0.0/tests/test_risk.py +77 -0
  130. inspectra_cli-2.0.0/tests/test_robots.py +49 -0
  131. inspectra_cli-2.0.0/tests/test_safety.py +196 -0
  132. inspectra_cli-2.0.0/tests/test_sarif.py +121 -0
  133. inspectra_cli-2.0.0/tests/test_tls.py +94 -0
  134. inspectra_cli-2.0.0/tests/test_utils.py +88 -0
@@ -0,0 +1,18 @@
1
+ .git
2
+ .github
3
+ .venv
4
+ venv
5
+ dist
6
+ build
7
+ .secrets
8
+ tmp
9
+ demo-output
10
+ inspectra-report
11
+ __pycache__
12
+ *.pyc
13
+ .mypy_cache
14
+ .pytest_cache
15
+ .ruff_cache
16
+ coverage.xml
17
+ .coverage
18
+ **/*.bak
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: Bug report
3
+ about: Report a problem with Inspectra
4
+ labels: bug
5
+ ---
6
+
7
+ **Describe the bug**
8
+ A clear description of what went wrong.
9
+
10
+ **Command you ran**
11
+
12
+ ```
13
+ inspectra scan ... (full command)
14
+ ```
15
+
16
+ **Expected behavior**
17
+ What you expected to happen.
18
+
19
+ **Actual behavior**
20
+ What actually happened (include relevant console output or report excerpt).
21
+
22
+ **Environment**
23
+ - OS:
24
+ - Python version:
25
+ - Inspectra version (`inspectra --version`):
26
+ - Nmap installed (yes/no):
27
+
28
+ **Additional context**
29
+ Anything else that helps reproduce the issue. ⚠️ Redact any sensitive data
30
+ from reports or logs before pasting.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: Feature request
3
+ about: Suggest an improvement to Inspectra
4
+ labels: enhancement
5
+ ---
6
+
7
+ **Problem to solve**
8
+ What are you trying to do that Inspectra cannot?
9
+
10
+ **Proposed solution**
11
+ What should happen instead?
12
+
13
+ **Fit with the philosophy**
14
+ Inspectra only observes, assesses, explains and reports — never exploits.
15
+ Explain how this feature stays within that boundary.
16
+
17
+ **Alternatives considered**
18
+ Other approaches you have thought of.
19
+
20
+ **Additional context**
21
+ Any other context, mockups or examples.
@@ -0,0 +1,24 @@
1
+ ---
2
+ name: New check proposal
3
+ about: Propose a new assessment check for Inspectra
4
+ labels: enhancement, check
5
+ ---
6
+
7
+ **Check name**
8
+ e.g. `cookie-attributes`
9
+
10
+ **What it observes**
11
+ What does the check look at? (headers, responses, DNS records, …)
12
+
13
+ **Evidence source**
14
+ Which request(s) or cached data does it use? Inspectra prefers reusing the
15
+ cached HTTP response over new requests.
16
+
17
+ **Possible findings and severities**
18
+ Sketch the rules: observation → severity → confidence.
19
+
20
+ **Sample evidence**
21
+ Example header/response/DNS data the check would capture.
22
+
23
+ **References**
24
+ Standards, documentation or prior art that support the check.
@@ -0,0 +1,41 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main, master]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ fail-fast: false
13
+ matrix:
14
+ python-version: ["3.11", "3.12"]
15
+
16
+ steps:
17
+ - uses: actions/checkout@v4
18
+
19
+ - name: Set up Python ${{ matrix.python-version }}
20
+ uses: actions/setup-python@v5
21
+ with:
22
+ python-version: ${{ matrix.python-version }}
23
+ cache: pip
24
+
25
+ - name: Install dependencies
26
+ run: |
27
+ python -m pip install --upgrade pip
28
+ pip install -e ".[dev]"
29
+
30
+ - name: Lint (ruff)
31
+ run: ruff check .
32
+
33
+ - name: Format check (ruff)
34
+ run: ruff format --check .
35
+
36
+ - name: Type check (mypy)
37
+ run: mypy
38
+
39
+ - name: Test (pytest)
40
+ run: |
41
+ pytest --cov=inspectra --cov-report=xml --cov-report=term-missing -q --tb=short
@@ -0,0 +1,45 @@
1
+ name: Docker
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ubuntu-latest
11
+ permissions:
12
+ contents: read
13
+ packages: write
14
+
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - name: Set up Docker Buildx
19
+ uses: docker/setup-buildx-action@v3
20
+
21
+ - name: Log in to GHCR
22
+ uses: docker/login-action@v3
23
+ with:
24
+ registry: ghcr.io
25
+ username: ${{ github.actor }}
26
+ password: ${{ secrets.GITHUB_TOKEN }}
27
+
28
+ - name: Docker metadata
29
+ id: meta
30
+ uses: docker/metadata-action@v5
31
+ with:
32
+ images: ghcr.io/shashu123456/inspectra
33
+ tags: |
34
+ type=ref,event=tag
35
+ type=raw,value=latest
36
+
37
+ - name: Build and push
38
+ uses: docker/build-push-action@v6
39
+ with:
40
+ context: .
41
+ platforms: linux/amd64,linux/arm64
42
+ push: true
43
+ tags: ${{ steps.meta.outputs.tags }}
44
+ cache-from: type=gha
45
+ cache-to: type=gha,mode=max
@@ -0,0 +1,37 @@
1
+ name: Pages
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ paths: ["site/**", ".github/workflows/pages.yml"]
7
+ workflow_dispatch:
8
+
9
+ permissions:
10
+ contents: read
11
+ pages: write
12
+ id-token: write
13
+
14
+ concurrency:
15
+ group: "pages"
16
+ cancel-in-progress: true
17
+
18
+ jobs:
19
+ deploy:
20
+ environment:
21
+ name: github-pages
22
+ url: ${{ steps.deployment.outputs.page_url }}
23
+ runs-on: ubuntu-latest
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+
27
+ - name: Configure GitHub Pages
28
+ uses: actions/configure-pages@v5
29
+
30
+ - name: Upload Pages artifact
31
+ uses: actions/upload-pages-artifact@v3
32
+ with:
33
+ path: site
34
+
35
+ - name: Deploy to GitHub Pages
36
+ id: deployment
37
+ uses: actions/deploy-pages@v4
@@ -0,0 +1,34 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ jobs:
8
+ release:
9
+ runs-on: ubuntu-latest
10
+ environment: pypi
11
+ permissions:
12
+ contents: read
13
+ id-token: write
14
+
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - name: Set up Python
19
+ uses: actions/setup-python@v5
20
+ with:
21
+ python-version: "3.11"
22
+
23
+ - name: Install build dependencies
24
+ run: |
25
+ python -m pip install --upgrade pip build twine
26
+
27
+ - name: Build sdist and wheel
28
+ run: python -m build
29
+
30
+ - name: Check distributions
31
+ run: twine check dist/*
32
+
33
+ - name: Publish to PyPI
34
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,36 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+
8
+ # Virtual environments
9
+ .venv/
10
+ venv/
11
+
12
+ # Tooling caches
13
+ .coverage
14
+ coverage.xml
15
+ htmlcov/
16
+ .pytest_cache/
17
+ .mypy_cache/
18
+ .ruff_cache/
19
+ .cache/
20
+
21
+ # Scan output (generated reports)
22
+ inspectra-report/
23
+ demo-output/
24
+
25
+ # Local scratch
26
+ tmp/
27
+
28
+ # Locally regenerated sample reports (committed copy lives in examples/sample-report/)
29
+ sample-output/
30
+
31
+ # Secrets (API tokens, credentials) — never commit
32
+ .secrets/
33
+
34
+ # OS noise
35
+ .DS_Store
36
+ Thumbs.db
@@ -0,0 +1,77 @@
1
+ # Changelog
2
+
3
+ All notable changes to Inspectra are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions
5
+ follow [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ### Added
10
+
11
+ - **Deterministic replay (M4):** `--save-fixtures DIR` records every HTTP
12
+ request/response to disk; `--replay DIR` replays scans entirely from disk
13
+ with zero network I/O. Two runs against the same fixtures produce
14
+ byte-identical JSON reports (modulo timestamps).
15
+ - **`evidence_hash` on findings:** `sha256` of canonical JSON evidence
16
+ (truncated to 16 chars), stored on every `Finding` and emitted in JSON
17
+ reports and SARIF `properties.evidenceHash`.
18
+ - **SARIF output:** `--format sarif` produces SARIF 2.1.0 compatible output
19
+ consumable by GitHub Code Scanning.
20
+ - **Baseline diff:** `--save-baseline` / `--baseline` compare scans against
21
+ a previous run; `--fail-on` applies only to new findings.
22
+ - **SSRF hardening:** validated IP pinning (DNS rebinding protection),
23
+ explicit blocked-network list including CGNAT (100.64/10), HTTPS→HTTP
24
+ downgrade rejection, per-redirect-hop re-validation.
25
+ - **Evidence redaction:** header lines, URL userinfo/query tokens, and JWTs
26
+ are redacted before any reporter serializes them. `--no-redact` disables
27
+ with a stderr warning.
28
+ - **Hosted sample report:** a static report and supporting files are hosted on
29
+ GitHub Pages at https://shashu123456.github.io/Inspectra/ for recruiter
30
+ review without installing anything.
31
+
32
+ ### Changed
33
+
34
+ - **CLI:** `--format` now accepts `sarif` and comma-separated lists
35
+ (`sarif,json,markdown`); `-o/--output` writes a single-format report to
36
+ an exact path; `--fail-on` accepts `none|low|medium|high` and works
37
+ without a baseline.
38
+ - **Reports:** JSON includes `evidence_hash` per finding plus `scope` and
39
+ `redaction` metadata; SARIF includes `evidenceHash` in result properties
40
+ and scope/redaction in run properties.
41
+
42
+ ## [1.0.0] — 2026-09-08
43
+
44
+ Initial public release.
45
+
46
+ ### Added
47
+
48
+ - **Assessment checks (8):** DNS record analysis, Nmap port discovery
49
+ (top-1000 default, explicit lists, skip), HTTP analysis (redirects,
50
+ error states, server disclosure), TLS certificate inspection (expiry,
51
+ self-signed, hostname mismatch, protocol versions), security header
52
+ assessment (9 rules), technology fingerprinting (24 signatures),
53
+ robots.txt inspection, and opt-in rate-limited directory observation.
54
+ - **Explainable findings:** every finding carries observation, impact
55
+ reasoning, evidence, confidence, severity and a concrete
56
+ recommendation.
57
+ - **Risk engine:** severity × confidence rubric producing a 0–100
58
+ posture score with letter grade (A+ … F).
59
+ - **Reports:** JSON (always), Markdown (default), and a polished,
60
+ self-contained HTML report. All human-facing timestamps are displayed
61
+ in Indian Standard Time (IST, UTC+05:30).
62
+ - **CLI:** single `inspectra scan` command with Rich console output,
63
+ first-run authorization consent gate, and CI-friendly exit codes
64
+ (0 clean · 1 findings · 2 error).
65
+ - **Safety model:** passive GET-only assessment, timeouts on every
66
+ network operation, safe-by-default wordlists, authorization banner.
67
+ - **Live demo:** `demo/server.py` hosts a harmless misconfigured fixture
68
+ site plus a UI that runs real scans in the browser.
69
+ - **Project infrastructure:** test suite (89 tests, ~90% coverage) with
70
+ a local fixture server, strict mypy on `src/`, ruff lint + format,
71
+ GitHub Actions CI on Python 3.11/3.12, issue templates, and sample
72
+ reports under `examples/`.
73
+
74
+ ### Security
75
+
76
+ - Safe-by-design: no exploitation, brute-forcing, or payload delivery;
77
+ the check registry and contribution policy enforce it.
@@ -0,0 +1,63 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as members, contributors, and leaders pledge to make participation in the
6
+ Inspectra community a harassment-free experience for everyone, regardless of
7
+ age, body size, visible or invisible disability, ethnicity, sex
8
+ characteristics, gender identity and expression, level of experience,
9
+ education, socio-economic status, nationality, personal appearance, race,
10
+ religion, or sexual identity and orientation.
11
+
12
+ We pledge to act and interact in ways that contribute to an open, welcoming,
13
+ diverse, inclusive, and healthy community.
14
+
15
+ ## Our Standards
16
+
17
+ Examples of behavior that contributes to a positive environment include:
18
+
19
+ * Demonstrating empathy and kindness toward other people
20
+ * Being respectful of differing opinions, viewpoints, and experiences
21
+ * Giving and gracefully accepting constructive feedback
22
+ * Accepting responsibility and apologizing to those affected by our mistakes,
23
+ and learning from the experience
24
+ * Focusing on what is best not just for us as individuals, but for the overall
25
+ community
26
+
27
+ Examples of unacceptable behavior include:
28
+
29
+ * The use of sexualized language or imagery, and sexual attention or advances
30
+ of any kind
31
+ * Trolling, insulting or derogatory comments, and personal or political attacks
32
+ * Public or private harassment
33
+ * Publishing others' private information, such as a physical or email address,
34
+ without their explicit permission
35
+ * Other conduct which could reasonably be considered inappropriate in a
36
+ professional setting
37
+
38
+ ## Enforcement Responsibilities
39
+
40
+ Community leaders are responsible for clarifying and enforcing our standards
41
+ of acceptable behavior and will take appropriate and fair corrective action in
42
+ response to any behavior that they deem inappropriate, threatening, offensive,
43
+ or harmful.
44
+
45
+ ## Scope
46
+
47
+ This Code of Conduct applies within all community spaces, and also applies
48
+ when an individual is officially representing the community in public spaces.
49
+
50
+ ## Enforcement
51
+
52
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be
53
+ reported to the community leaders responsible for enforcement through the
54
+ repository's listed contact. All complaints will be reviewed and investigated
55
+ promptly and fairly.
56
+
57
+ All community leaders are obligated to respect the privacy and security of
58
+ the reporter of any incident.
59
+
60
+ ## Attribution
61
+
62
+ This Code of Conduct is adapted from the
63
+ [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
@@ -0,0 +1,86 @@
1
+ # Contributing to Inspectra
2
+
3
+ Thanks for your interest in improving Inspectra! This project follows one
4
+ rule above all others:
5
+
6
+ > **Inspect. Observe. Assess. Explain. Report. Never exploit.**
7
+
8
+ Any contribution that adds exploitation, brute-forcing, payload delivery or
9
+ attack tooling will be declined, no matter how well implemented.
10
+
11
+ ## Project Setup
12
+
13
+ ```bash
14
+ git clone <repository-url>
15
+ cd inspectra
16
+ python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
17
+ pip install -e ".[dev]"
18
+ ```
19
+
20
+ Install [Nmap](https://nmap.org) if you want to work on the port check
21
+ (see `docs/usage.md` for per-OS instructions).
22
+
23
+ ## Running the Quality Gates
24
+
25
+ ```bash
26
+ ruff check . # lint
27
+ ruff format . # formatting (run before committing)
28
+ mypy # type checking
29
+ pytest # tests with coverage
30
+ ```
31
+
32
+ CI runs all four on Python 3.11 and 3.12. All tests run against a local
33
+ fixture server — the suite never touches the internet.
34
+
35
+ ## Adding a Check
36
+
37
+ This is the most valuable kind of contribution. It is deliberately small:
38
+
39
+ 1. Create `src/inspectra/checks/<name>.py` exposing:
40
+
41
+ ```python
42
+ def run(target: Target, context: ScanContext) -> list[Finding]:
43
+ ```
44
+
45
+ 2. Register it in `ALL_CHECKS` and `DEFAULT_CHECK_ORDER`
46
+ (`src/inspectra/checks/__init__.py`). Put it *after* the checks whose
47
+ cached data it consumes (the HTTP check caches the primary response in
48
+ the context).
49
+ 3. If the check needs rules or signatures, add them to
50
+ `src/inspectra/data/` as JSON — not code.
51
+ 4. Write unit tests in `tests/` (mock the network; use the fixtures in
52
+ `conftest.py` where possible).
53
+ 5. Document the check in `docs/usage.md`.
54
+ 6. Open a pull request using the template.
55
+
56
+ ### The finding contract
57
+
58
+ Every finding must be explainable. Fill in all six fields:
59
+
60
+ | Field | Question |
61
+ |-------|----------|
62
+ | `rule_id` | Stable ID like `HDR-001` (prefix per check, never reused) |
63
+ | `description` | What was observed? |
64
+ | `why_it_matters` | Why should the reader care? |
65
+ | `evidence` | Raw proof, truncated to stay readable |
66
+ | `confidence` | low / medium / high |
67
+ | `severity` | info / low / medium / high |
68
+ | `recommendation` | A concrete next step |
69
+
70
+ ## Code Style
71
+
72
+ * Python 3.11+, full type hints, `from __future__ import annotations`.
73
+ * Dataclasses over classes; docstrings on every public object.
74
+ * One module, one responsibility. If a file needs a "misc" section, split it.
75
+ * No new runtime dependencies without a written justification in the PR.
76
+
77
+ ## Reporting Issues
78
+
79
+ Use the issue templates. For security issues in Inspectra itself, see
80
+ [SECURITY.md](SECURITY.md) — never open a public issue.
81
+
82
+ ## Roadmap Policy
83
+
84
+ Ideas that don't fit the current release belong in
85
+ [`docs/roadmap.md`](docs/roadmap.md), not in the codebase. Propose the
86
+ addition in your issue if that's where your idea belongs.
@@ -0,0 +1,21 @@
1
+ FROM python:3.11-slim
2
+
3
+ ENV PYTHONDONTWRITEBYTECODE=1 \
4
+ PYTHONUNBUFFERED=1 \
5
+ PIP_NO_CACHE_DIR=1
6
+
7
+ RUN apt-get update \
8
+ && apt-get install -y --no-install-recommends nmap ca-certificates \
9
+ && rm -rf /var/lib/apt/lists/*
10
+
11
+ RUN useradd --create-home --uid 10001 inspectra
12
+
13
+ WORKDIR /app
14
+ COPY pyproject.toml README.md LICENSE ./
15
+ COPY src ./src
16
+ RUN pip install .
17
+
18
+ WORKDIR /data
19
+ USER inspectra
20
+ ENTRYPOINT ["inspectra"]
21
+ CMD ["--help"]
@@ -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.