# Contributing to openclaw-scan
Thank you for helping make agentic AI installations safer! This guide covers everything you need to contribute.
---
## Development setup
**Prerequisites:** Rust 1.75+ (install via [rustup](https://rustup.rs))
```bash
git clone https://gitlab.com/pyratzlabs/software/Openclaw_Security_Tooling_CLI
cd Openclaw_Security_Tooling_CLI
cargo build
cargo test --all
```
---
## Quality gates (all required to pass CI)
```bash
cargo fmt --check # formatting
cargo clippy -- -D warnings # lints (zero warnings policy)
cargo test --all # all unit + integration tests
```
Run them all at once:
```bash
make check
```
---
## Adding a new scanner rule
1. Find the relevant scanner in `src/scanner/` (or create a new one).
2. Add the detection logic inside the scanner's `scan()` method.
3. Return a `Finding` using `Finding::new(...)` with an appropriate severity, clear title, and concrete remediation steps.
4. **Always redact secrets** before storing in `evidence` — use `crate::finding::redact(value, N)`.
5. Add a unit test inside the same file covering both the positive case (should detect) and the negative case (should not false-positive).
6. Add or update an integration test in `tests/integration/` using a fixture from `tests/fixtures/`.
---
## Adding a new secret pattern
1. Open `src/scanner/secrets.rs`.
2. Add a new `SecretPattern` entry to the `PATTERNS` static. Include:
- `name`: human-readable name of the credential type
- `severity`: `Critical` for private keys and direct API keys; `High` for others
- `keep`: number of non-redacted prefix characters to show in evidence
- `re`: the regex (use a linear-time pattern — no backtracking)
3. Add a unit test in the same file: one positive case with a real-format fake token and one negative case.
4. Update the fixture `tests/fixtures/history_with_secrets.jsonl` if needed.
**Never include real credentials in tests.** All fixture tokens must be obviously fake (e.g. `AKIAIOSFODNN7EXAMPLE`, repeated chars).
---
## Commit message format
```
<type>(<scope>): <short description>
[optional body]
```
Types: `feat`, `fix`, `refactor`, `test`, `docs`, `ci`, `chore`
Examples:
- `feat(secrets): add Cohere API key pattern`
- `fix(config): handle missing permissions key gracefully`
- `test(hooks): add integration test for outbound curl hook`
---
## Pull request checklist
- [ ] `cargo fmt --check` passes
- [ ] `cargo clippy -- -D warnings` passes
- [ ] All existing tests pass (`cargo test --all`)
- [ ] New tests added for new behaviour (both positive and negative)
- [ ] No real credentials or sensitive data in any file
- [ ] Remediation text is concrete and actionable
---
## Reporting security issues
Please **do not** open a public issue for security vulnerabilities in this tool itself. Email `hello@pyratzlabs.com` with the subject "Security disclosure: openclaw-scan".