# Contributing to TrueVuln

Thanks for wanting to help. TrueVuln aggregates and enriches vulnerability data from a
lot of moving upstream sources, so almost every kind of contribution is useful --
especially the boring ones.

## Contributions that need no CLA

Open an issue. No agreement, no bot, no friction:

- **Bug reports** -- include the scanner source (Wazuh / Nessus / Intune / Defender),
  the CVE or asset involved, and what you expected instead
- **Upstream data problems** -- a CVE with a wrong score, an EOL product not detected,
  a false positive from a specific scanner
- **Feature requests and discussion**
- **Documentation feedback**

## Contributions that need a CLA

Code and documentation changes submitted as pull requests require the
[Contributor License Agreement](CLA.md).

**Why:** TrueVuln is open core (see [LICENSING.md](LICENSING.md)). The CLA grants the
maintainer permission to distribute contributed code under both AGPL-3.0 and commercial
terms. **You keep the copyright to your work** and can still use, license, or distribute
it anywhere else however you like.

**How:** Open your pull request. A bot comments asking you to confirm the CLA. You reply
with the sentence it gives you. That is it -- once, ever, for all future contributions.

If you do not want to sign, that is fine. Open an issue describing the fix instead; a
maintainer can implement it.

## Before you open a pull request

1. **Open an issue first** for anything non-trivial. Saves you writing code that goes in
   a direction the project is not taking.
2. **One concern per pull request.** A bug fix and a refactor in the same diff is two
   pull requests.
3. **Add a test.** Anything with a branch, a parser, a version comparison, or a scoring
   rule needs a test that fails without your change. `tests/` shows the existing style.
4. **Do not commit secrets.** No API keys, tokens, real hostnames, real asset data, or
   customer names -- not in code, not in tests, not in fixtures. Use the placeholder
   style from `.env.example`.
5. **Sanitise fixtures.** If you add scanner output as a test fixture, strip hostnames,
   IP addresses, serial numbers, and user names first.

## Development setup

```bash
cp .env.example .env     # fill in your own values
docker compose up -d
```

Or without Docker, see `README.DEV.md`.

Run the tests:

```bash
pytest
```

## What makes a good contribution here

TrueVuln's value is accuracy. A detection that fires on the wrong host is worse than no
detection, because it burns the operator's trust. So:

- **Version and build comparisons must be exact.** Family-matched, range-bounded. A
  Windows 11 host must never match a Server-only fix, even on a shared build line.
- **Prefer authoritative sources.** Vendor advisories over aggregators, aggregators over
  heuristics.
- **Findings must be able to close themselves.** If a detection can fire, it needs a path
  to auto-resolve when the condition no longer holds. Stale findings are noise.
- **Fail loud in ingest, fail quiet in the UI.** A broken upstream feed should be visible
  in logs and status, not silently produce empty results.

## Commit messages

Conventional Commits, scoped to the area:

```
fix(msrc): the ingest sorted the monthly index by revision date, not month
feat(nessus): import plugin output as remediation text
```

Describe what actually changed and why. The subject line should make sense to someone
reading `git log` two years from now.

## Security issues

**Do not open a public issue for a security vulnerability in TrueVuln itself.**
See [SECURITY.md](SECURITY.md) for private reporting.