Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
78 lines (64 loc) · 3.02 KB

CONTRIBUTING.md

File metadata and controls

78 lines (64 loc) · 3.02 KB
Raw

Contributing to pnx-mcp-audit

Thanks for considering a contribution. The project is small on purpose; the bar for new code is "would a senior security engineer audit it line by line and trust it?".

What we are looking for

Highest-value contributions, in priority order:

  1. New check rules. If you have seen a class of bug in MCP servers in the wild, file an issue with a sample descriptor or server snippet that triggers it. We will add a rule with a stable MCP-NNN id.
  2. Bug fixes. Anything that makes the audit produce a wrong finding (false positive or false negative) is high priority.
  3. Active probes. The --probe flag is reserved for active tests (safe tool invocations that elicit specific server behaviours). Probes need to be careful: they must never modify server state. See docs/checks.md for the MCP-100+ design space.
  4. Transport coverage. Streamable HTTP works today; the future work is robust SSE chunking + a WebSocket transport.
  5. CI integrations. Recipes for GitLab, Jenkins, Drone, Buildkite, etc., welcome in docs/usage.md.

Lower priority

  • Cosmetic terminal-output changes (the current style is intentional).
  • Adding optional third-party Go dependencies. The project is stdlib-only on purpose; new dependencies need a strong case.
  • Refactors that do not change behaviour.

Process

  1. Open an issue describing the change before writing code, unless it is a small bug fix.
  2. Fork, branch, commit, push, open a PR.
  3. Every PR must:
    • Pass go vet ./... + gofmt
    • Pass go test -race ./...
    • Include tests for new check rules (table-driven; see internal/checks/static_test.go)
  4. Sign your commits if you can (git commit -s). Not strictly required but appreciated.

Adding a new check rule

  1. Pick the next MCP-NNN id (static rules are <100, active probes are 100+).
  2. Implement the rule in internal/checks/static.go as a struct + Meta() + Run(snap *mcp.Snapshot) []audit.Finding.
  3. Register it in DefaultRegistry().
  4. Add table-driven tests in internal/checks/static_test.go.
  5. Document the rule in docs/checks.md with severity, OWASP / MITRE mapping, and remediation guidance.
  6. If the mock server in examples/mock-server does not already trigger the rule, add a minimal descriptor that does (without complicating the existing fixture beyond recognition; create a second fixture if cleaner).

Code style

  • gofmt is law.
  • Function comments explain WHY. Avoid restating WHAT (the code shows that).
  • No external dependencies. If a piece of stdlib is awkward, pick the awkward stdlib path.
  • Error messages start lowercase and are wrapped with %w when forwarded.
  • Severity is conservative: HIGH is for things a senior reviewer would flag in a real PR. CRITICAL is "do not deploy with this in place". Most useful new rules are MEDIUM.

License

By contributing, you agree your contribution is licensed under the Apache License 2.0, the same license as this project.