crowdsec

# Working in this repository

For anyone opening a pull request against crowdsec: human, or LLM.
`CLAUDE.md` is a symlink to this file.

PRs that ignore the rules below are unlikely to be reviewed.

## Keep the change small

- One concern per PR. A bug fix and a refactor are two PRs.
- No drive-by reformatting, renaming, or restructuring.
- Don't bump dependencies. Dependabot owns `go.mod` and `go.sum`.
- If the diff is over ~400 lines, either split it, or say in the first line of the PR body why
  it can't be split.

## A human must have tested and reviewed this

Before you open the PR, a human must have:

- read the diff line by line, and
- run the change, or supervised and independently verified the testing an agent did.

Say which, in the PR body.

### Automated checks

- While iterating: `go test ./pkg/<what you changed>/...`
- Full suite: `make test`. Needs `gotestsum` installed, and `make localstack` running in
  another shell, or set `TEST_LOCAL_ONLY=1` to skip the tests that need containers.
- If you touched `pkg/exprhelpers`, use `make test`.
- Lint while iterating: `golangci-lint run ./pkg/<what you changed>/...`
- Before pushing: `make lint`. It lints linux, windows and freebsd, same as CI — so expect
  findings outside your change if it's platform-specific.
- Use golangci-lint v2.13, the version CI pins. Other versions report different things.
- Don't restructure working code to satisfy a linter that's switched off. Check the `disable:`
  list in `.golangci.yml` before "fixing" something it never complained about.

### Running it for real

This is how you can spin a simple test instance: 
```
make build                        # crowdsec, cscli and the notification plugins
scripts/test_env.sh -d ./tests    # working config tree in ./tests
cd ./tests
$EDITOR config/acquis.yaml        # point it at a log file you can write to
./crowdsec -c dev.yaml
```

`scripts/test_env.sh` copies the binaries out of the source tree, so `make build` has to run
first.

Look up the crowdSec-skill to deploy, configure and troubleshoot CrowdSec instances: https://www.skills.sh/crowdsecurity/crowdsec-skill/crowdsec 

## Tests

- New behaviour needs a test.
- A test must fail when the behaviour it covers breaks. No tautological tests: don't check that a
  mock returns what you told it to, that a setter sets, or that the code does what it says. More
  test lines is not better; a large suite that misses the obvious case is worse than a small one.
- Test the cases the change exists for, not just the happy path. Don't skip the hard one with a
  comment: a skipped test for the scenario that matters is a missing test.
- Refactoring or replacing an existing component: first cover its current user-visible behaviour
  with tests, and make them pass unchanged before and after. List every intended behaviour
  change in the PR body.
- `require` over `assert` — a failed `assert` keeps going and buries the real error.
- Table-driven, with `t.Run` subtests.
- Unit tests live next to the code. Functional tests are BATS under `test/bats/`; see
  `test/README.md`.

## Be concise

Humans read your output, keep verbosity to minimum.


**PR and issue bodies** — what changed, why, and how it was tested. Nothing else. No prose
restatement of the diff. Any issue or PR text should be under 5k characters.

Instead of:

> ## Summary
> This PR introduces a comprehensive enhancement to the syslog acquisition module...
> ## Motivation
> Currently, the existing implementation suffers from a limitation whereby...
> ## Implementation Details
> - ✅ Added a new `timeout` field to the configuration struct
> - ✅ Updated the parsing logic to respect the new field
> ## Testing Strategy
> Comprehensive unit tests have been added to ensure correctness...

Write:

> syslog acquisition hung forever when the remote stopped sending. Adds a configurable
> `timeout` (default 30s) and closes the connection when it expires.
>
> Tested: `go test ./pkg/acquisition/modules/syslog/...`, plus a local run against a syslog
> source that goes silent — connection now drops after 30s instead of hanging.

**Code comments** — explain why, not what. If the comment restates the line under it, delete
it. Keep them short and to the point, not prose: a comment should rarely be longer than the code
it describes. A 20-line comment over a 5-line function is noise.

**Review replies** — answer the question that was asked. Don't re-explain the PR, and don't
paste your agent's output into the thread. Read it, then reply in your own words, in a few
lines.

## Don't break these

Each one is a one-way door — users are already depending on it.

- **LAPI/CAPI payloads** — change `pkg/models/localapi_swagger.yaml` or
  `pkg/modelscapi/centralapi_swagger.yaml` and regenerate. Never edit the generated Go by hand.
- **Database schema** — your migration lands on existing user databases.
- **Config keys** in `pkg/csconfig` — renaming or removing one breaks upgrades.
- **`cscli -o json` and `-o raw`** — bouncers and scripts parse these. `-o human` is the only
  output you can freely change.

If you have to break one of these, say so explicitly at the top of the PR body.

## Commits and PRs

- Base branch is `master`.
- Commit titles are loose: `area: what changed` or `type(scope): what changed`, both fine.
- Never write `(#1234)` in a commit title. Squash-merge adds it. Yours will be wrong.
- One `kind/*` label and one `area/*` label.

More agent context in crowdsecurity/crowdsec

One other file this repository gives its agents.