Skip to content

Latest commit

 

History

History
52 lines (41 loc) · 1.9 KB

CONTRIBUTING.md

File metadata and controls

52 lines (41 loc) · 1.9 KB

Contributing

Contributions are welcome. This project values clarity, safety, and honest reporting over feature count.

Development setup

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest

Principles

  1. Checks return findings; they never print or exit. The numbered scripts and the orchestrator are the only places that touch I/O and process exit codes.
  2. Separate observation from proof. Use status honestly: confirmed only for reproducible, in-scope demonstrations; otherwise suspected/inconclusive with a manual_verification note.
  3. Safety first. All network traffic goes through HttpClient, which enforces scope and the request budget. Do not bypass it.
  4. No secrets, ever. Never log or serialise raw credentials. Use authentication.redact and Identity.safe_summary.
  5. Offline tests. Tests must not depend on the public internet. Use httpx.MockTransport and the bundled api_pentesting.demo.LabApp.

Adding a new check

  1. Add a module under src/api_pentesting/checks/ exposing a run_*/audit function that returns list[Finding].
  2. Cite OWASP references via checks/_common.py.
  3. Add unit tests covering a secure posture (quiet) and a vulnerable posture (fires) using the lab target.
  4. To expose it in the orchestrator, register a category runner in orchestrator.py (CATEGORY_RUNNERS).
  5. If it warrants a standalone entry point, add a numbered script and a guide in docs/scripts/.

Style

  • Python 3.10+, type hints where they add clarity.
  • Short functions, explicit names, docstrings stating purpose/params/returns/limits.
  • Keep dependencies minimal and justified.

Before opening a PR

  • pytest passes.
  • New behaviour has tests.
  • No secrets, no real target URLs, no committed reports.
  • Docs updated if behaviour or CLI changed.