# Contributing to ExploitSpec

ExploitSpec exists to make proven security findings durable, public tooling. We
welcome code, documentation, design criticism, sanitized real-world specs, and
reproducible bug reports.

The project has one free, open-source edition. Contributions should strengthen
the local-first CLI rather than introduce accounts, telemetry, or paid gates.

By participating, you agree to follow the
[Code of Conduct](CODE_OF_CONDUCT.md).

## Before you start

For a small fix, open a focused pull request. For a new format feature, behavior
change, dependency, or broad refactor, start with an issue so the design and
safety implications can be discussed before substantial work.

Security vulnerabilities in ExploitSpec itself must not be reported through a
public issue. Follow [SECURITY.md](SECURITY.md).

## Development setup

Requirements:

- the latest patched release of Go 1.25 or newer;
- Git;
- a loopback test service or an explicitly authorized test target for manual
  runner checks.

From the repository root:

```bash
go mod download
go build ./cmd/exploitspec
go test ./...
go vet ./...
```

Format changed Go files before submitting:

```bash
gofmt -w path/to/changed.go
```

Do not point test specs at production systems. Automated and manual tests should
prefer `httptest` or a disposable loopback service with synthetic data.

## A good contribution

A strong pull request is:

- narrow enough to review;
- explicit about the user problem;
- covered by tests proportional to its risk;
- documented when it changes the CLI, YAML, reports, limits, or safety behavior;
- free of credentials, customer data, real exploit targets, and generated build
  artifacts;
- backward-compatible unless a breaking change was discussed and accepted.

Avoid combining formatting churn, refactoring, and behavioral work in one pull
request.

## Change workflow

1. Fork the repository and create a branch from the current default branch.
2. Reproduce the problem or describe the intended behavior.
3. Make the smallest coherent change.
4. Add or update tests.
5. Run formatting, tests, vetting, and a local build.
6. Update relevant documentation.
7. Open a pull request with the motivation, behavior, validation performed, and
   any security or compatibility implications.

A useful pull request description answers:

- What problem does this solve?
- What behavior changes?
- How was it tested?
- Does it change network reachability, interpolation, secret handling, report
  contents, or state-changing request behavior?
- Does it alter the version 1 YAML contract or exit codes?

## Testing guidance

Tests should be deterministic, local, and fast. Use Go's `httptest` package for
HTTP behavior whenever possible.

At minimum, consider these cases for runner or format changes:

- the expected pass path;
- an invariant failure path;
- malformed or unknown YAML fields;
- missing environment and captured variables;
- actor cookie isolation;
- redirects to allowed and rejected hosts;
- metadata endpoint rejection;
- oversized responses and timeouts;
- sensitive values not being copied unnecessarily into reports;
- exit-code differences between failure and execution error.

Safety fixes should include a regression test that fails without the fix.

## Changing the YAML format

The YAML document is the project's most important compatibility surface.

When adding or modifying a field:

1. update the types and strict validation in `internal/spec`;
2. define unambiguous runtime behavior in `internal/runner`;
3. cover valid, invalid, and adversarial inputs;
4. update [docs/specification.md](docs/specification.md);
5. update [docs/architecture.md](docs/architecture.md) if data flow or the threat
   model changes;
6. explain compatibility in the pull request.

Do not silently accept and ignore new fields. Do not add arbitrary script
execution as an escape hatch; that changes the security model and requires prior
design discussion.

## Changing safety behavior

Changes that expand network reachability or execution power deserve extra
scrutiny. This includes host matching, redirects, DNS resolution, proxy use,
HTTP methods, TLS, file access, environment handling, response limits, and
templating.

Document both what the control prevents and what remains outside its boundary.
Security language must describe tested behavior without implying that the CLI is
a sandbox or grants authorization to test a target.

## Documentation

Documentation is part of the product. Prefer short sentences, runnable examples,
and exact claims. Keep the primary documentation in international English so it
is accessible to the broadest contributor community.

When documenting current behavior, verify it in code or with a local
reproduction. Planned features belong in [ROADMAP.md](ROADMAP.md), not in the
“works today” sections.

## Dependencies

ExploitSpec aims to keep its dependency and supply-chain surface small. Before
adding a module, explain why the standard library or current dependencies are
insufficient, and consider maintenance activity, license, transitive packages,
and security history.

Run `go mod tidy` only when module requirements genuinely changed, and include
the resulting `go.mod` and `go.sum` updates in the same pull request.

## Commit and review hygiene

Write concise, imperative commit subjects. Maintainers may ask for revisions,
additional tests, a smaller scope, or a design discussion. Review focuses on
correctness, clarity, compatibility, safety, and maintainability—not on who
submitted the change.

Generated code or AI-assisted changes are welcome only when the contributor has
personally reviewed, understood, tested, and can maintain them. The contributor
remains responsible for correctness, provenance, and licensing.

## License of contributions

By intentionally submitting a contribution for inclusion in ExploitSpec, you
agree that it is provided under the repository's
[Apache License 2.0](LICENSE), in accordance with section 5 of that license. Do
not submit material you do not have the right to license.

Thank you for helping turn one-time security evidence into permanent public
infrastructure.