Before you start
The repository is the source of truth for process: the contribution guide covers branching and review etiquette, and AGENTS.md covers how the codebase expects to be changed. Read both before writing code. They answer most review comments in advance.
New here? Skim the docs and the safety model first. Changes to scope, policy, or tool execution only make sense once you understand what the gates are protecting.
What to expect
Mocked tests, strict gates, and docs in the same pull request. The list below is the standing contract. If your change weakens any of it, the review will ask you to strengthen it instead.
Tests
The suite is fully mocked. No live scanning; every subprocess and network call is faked. Safety-relevant code needs regression tests that prove the gate still holds.
CI
Every push and pull request runs the mocked suite plus coverage, lint and format checks, type checking, package builds, and the WebUI build and tests.
Quality gates
Static analysis and dependency review run on every change, with scheduled updates for packages, actions, and JavaScript dependencies.
Python
Follow the repository lint and format configuration and keep strict typing on security-sensitive paths. Match the style the file already uses.
TypeScript / WebUI
Type-check, build, and test the WebUI whenever you touch it. Run all three before asking for review, not after.
Docs discipline
Adding a flag, tool, or config key means updating the user-facing docs in the same pull request. Undocumented behavior does not ship.
How a change flows
Read the guide first
The contribution guide and AGENTS.md describe branching, review, and what a focused change looks like. Start there, not in the code.
Keep the change focused
One concern per pull request. A small diff that does one thing gets reviewed in days; a broad one waits for weeks.
Prove the safety story
Touching scope, policy, or tool execution means adding or updating the tests that guard it, and saying so in the PR description.
Update docs alongside
Flags, tools, and config keys land with their documentation. Link the pages you changed so reviewers can read them.
Checks before a PR
Run the same gates CI will run, locally, before you push. A green local run is the entry ticket for review.
python -m pytest tests/ -v
ruff check .
ruff format --check .
mypy --follow-imports=skip toolsIf you touched the WebUI, also type-check, build, and test it. If you added a flag, tool, or config key, verify every reference in the docs still matches reality.
Safety is non-negotiable
BreachPilot ships attack tooling, so its safeties are load-bearing: scope gating decides what may be touched, the target allowlist lock blocks everything else, and the audit trail records every decision. Contributions that relax any of the three will not merge. Changes that strengthen them get the fastest reviews.
Only test systems you own or have explicit written permission to assess, including when you are testing your own change. Develop against a lab you control, and keep the authorization in writing.