You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CLAUDE.md
+41Lines changed: 41 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,17 @@
3
3
Conventions for authoring this skill. This governs how skill content is **written** and
4
4
**validated**.
5
5
6
+
# General rules
7
+
8
+
Never open responses with filler phrases like "Great question!", "Of course!", "Certainly!", or similar warmups. Start every response with the actual answer. No preamble, no acknowledgment of the question.
9
+
10
+
Match response length to task complexity. Simple questions get direct, short answers. Complex tasks get full, detailed responses. Never pad responses with restatements of the question or closing sentences that repeat what you just said.
11
+
12
+
Before any significant task, show me 2-3 ways you could approach this work. Wait for me to choose before proceeding.
13
+
14
+
If you are uncertain about any fact, statistic, date, or piece of technical information: say so explicitly before including it. Never fill gaps in your knowledge with plausible-sounding information. When in doubt, say so.
15
+
16
+
6
17
## Writing style
7
18
8
19
-**Be concise.** Technical documentation, not an essay. Favor tables, command recipes, and short
@@ -20,6 +31,36 @@ Conventions for authoring this skill. This governs how skill content is **writte
20
31
-**Anchor to canonical docs.** Each reference doc cites the upstream CrowdSec docs URL it derives
21
32
from. Claims trace to canonical documentation, not to memory.
22
33
34
+
## Content structure
35
+
36
+
`SKILL.md` is the router — a symptom/intent-indexed table that points into `references/`.
37
+
All depth lives in `references/<area>/`, organized by the axis that fits the area:
|`debug/`|**kind**|`common/` (`triage`, `errors`, `platform-gotchas`) + `symptoms/` (`parsing`, `no-alerts`, `not-blocked`). Feature troubleshooting is *routed to* the feature's own dir (e.g. AppSec → `appsec/troubleshoot.md`), not duplicated under debug/. |
|**Debug — by symptom** · "logs not parsed", "0 parsed" |[references/debug/symptoms/parsing.md](./references/debug/symptoms/parsing.md)|
82
+
|**Debug — by symptom** · "no alerts firing" |[references/debug/symptoms/no-alerts.md](./references/debug/symptoms/no-alerts.md)|
83
+
|**Debug — by symptom** · "decision exists but not blocked" |[references/debug/symptoms/not-blocked.md](./references/debug/symptoms/not-blocked.md)|
84
+
|**Debug — by feature** · AppSec/WAF not blocking, false positives, captcha |[references/appsec/troubleshoot.md](./references/appsec/troubleshoot.md)|
83
85
| "switch from fail2ban" |[references/migrate/from-fail2ban.md](./references/migrate/from-fail2ban.md)*(TODO — stub)*|
84
86
85
87
For anything debug-shaped, the first move is almost always:
@@ -134,7 +136,7 @@ Where things live on a default bare-metal install:
134
136
Confirm with the user before any of these:
135
137
136
138
-`cscli decisions delete --all` — wipes every active ban including CAPI-pulled blocklists. Use targeted `delete -i`, `delete -r`, `delete --id`, `delete --origin lists --scenario <name>`.
137
-
- Editing hub-managed files under `/etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/` instead of the sibling `_custom/` directory — see [references/debug/triage.md](./references/debug/triage.md) § Hard don'ts.
139
+
- Editing hub-managed files under `/etc/crowdsec/{parsers,scenarios,collections,postoverflows,contexts}/` instead of the sibling `_custom/` directory — see [references/debug/common/triage.md](./references/debug/common/triage.md) § Hard don'ts.
138
140
- Disabling a signature collection wholesale to silence a false positive — pick the right suppression layer (allowlist / whitelist parser / postoverflow) per [references/configure/allowlists.md](./references/configure/allowlists.md) § Suppression mechanisms.
139
141
- Mutating host firewall state (firewall bouncer install, `ipset` flush, iptables↔nftables switch) without confirming — the firewall bouncer can wipe rule chains other tools depend on.
Copy file name to clipboardExpand all lines: skills/crowdsec/references/debug/common/errors.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,32 +30,32 @@ Match the error string the engine/bouncer printed to the row below.
30
30
31
31
| Error string | Cause | Fix |
32
32
|---|---|---|
33
-
|`datasource of type appsec: … cannot parse appsec configuration: [2:3] cannot unmarshal []interface {} into Go struct field Configuration.AppsecConfig of type string`|`appsec_config:` (singular) given a **list**| Use the **plural** key `appsec_configs:`for a list; singular takes one string. See [../appsec/configure.md](../appsec/configure.md). |
34
-
|`unable to initialize inband engine : invalid WAF config from string: failed to compile the directive "secrule": duplicated rule id 100`| Two appsec-configs on one listener pull the **same** underlying rule (e.g. both include `base-config`/`vpatch-*`) | Use non-overlapping configs, or just `crowdsecurity/appsec-default` alone. See [../appsec/configure.md](../appsec/configure.md). |
35
-
|`no appsec-rules found for pattern <name>`| A bare appsec-config was installed without its rules; engine expands globs at load, `cscli` does not | Install via the **collection** (`cscli collections install crowdsecurity/appsec-virtual-patching`), which pulls the rule graph. See [../appsec/deploy.md](../appsec/deploy.md). |
33
+
|`datasource of type appsec: … cannot parse appsec configuration: [2:3] cannot unmarshal []interface {} into Go struct field Configuration.AppsecConfig of type string`|`appsec_config:` (singular) given a **list**| Use the **plural** key `appsec_configs:`for a list; singular takes one string. See [../appsec/configure.md](../../appsec/configure.md). |
34
+
|`unable to initialize inband engine : invalid WAF config from string: failed to compile the directive "secrule": duplicated rule id 100`| Two appsec-configs on one listener pull the **same** underlying rule (e.g. both include `base-config`/`vpatch-*`) | Use non-overlapping configs, or just `crowdsecurity/appsec-default` alone. See [../appsec/configure.md](../../appsec/configure.md). |
35
+
|`no appsec-rules found for pattern <name>`| A bare appsec-config was installed without its rules; engine expands globs at load, `cscli` does not | Install via the **collection** (`cscli collections install crowdsecurity/appsec-virtual-patching`), which pulls the rule graph. See [../appsec/deploy.md](../../appsec/deploy.md). |
36
36
|`no such datasource` / sourcetype unknown |`source:`/`labels.type:` typo or a datasource the build doesn't support | Fix the key in the `acquis.d/*.yaml`; `crowdsec -t` points at the file:line. |
37
-
| Source reads lines but **0 parsed** | `type:` label doesn't match any installed parser | [parsing.md](./parsing.md). |
37
+
| Source reads lines but **0 parsed** | `type:` label doesn't match any installed parser | [parsing.md](../symptoms/parsing.md). |
38
38
39
39
## Permissions / OS
40
40
41
41
| Symptom | Cause | Fix |
42
42
|---|---|---|
43
-
|`permission denied` opening a log file; or source present but 0 lines read|`crowdsec` user can't read the file | `sudo -u crowdsec head <path>`; fix ownership/ACL. If that user *can* read it but the engine still can't, it's **SELinux/AppArmor** — `ausearch -m avc -ts recent` / `dmesg | grep DENIED`, then relabel/add policy (don't disable enforcement). |
43
+
|`permission denied` opening a log file; or source present but 0 lines read|`crowdsec` user can't read the file | `sudo -u crowdsec head <path>`; fix ownership/ACL. If that user *can* read it but the engine still can't, it's **SELinux/AppArmor** → [platform-gotchas.md](./platform-gotchas.md). |
44
44
| apt install of a bouncer hangs: `Failed to open terminal … debconf: whiptail output the above errors, giving up!` | A debconf dialog (e.g. pending-kernel notice) on a non-interactive shell | Re-run with `sudo DEBIAN_FRONTEND=noninteractive apt install -y …`. |
45
45
46
46
## LAPI / CAPI / auth
47
47
48
48
| Error | Cause | Fix |
49
49
|---|---|---|
50
50
| Agent: `unable to authenticate … machine not validated` | Agent machine not registered/validated with LAPI | `cscli machines list`; validate with `cscli machines validate <name>` (or re-`cscli machines add` on the agent). |
51
-
| Bouncer log: **HTTP 401** on decision pull | Bouncer key ≠ LAPI key (rotated, stale config, re-added) |`cscli bouncers list`; re-issue and paste the key into the bouncer config. [bouncer-not-blocking.md](./bouncer-not-blocking.md) §3. |
51
+
| Bouncer log: **HTTP 401** on decision pull | Bouncer key ≠ LAPI key (rotated, stale config, re-added) | `cscli bouncers list`; re-issue and paste the key into the bouncer config. [not-blocked.md](../symptoms/not-blocked.md) §3. |
52
52
| `cscli capi status` fails / CAPI register errors | Missing `online_api_credentials.yaml`, **clock skew**, or egress blocked to `api.crowdsec.net` | `cscli capi register` then reload; check `timedatectl` (TLS fails on skew); allow egress / set proxy. |
53
53
54
54
## Database
55
55
56
56
| Error | Cause | Fix |
57
57
|---|---|---|
58
-
|`database is locked` (sqlite) | Concurrent writers / slow disk; sqlite single-writer | Reduce write pressure; move `crowdsec.db` to faster storage;for multi-agent or high volume switch the backend to PostgreSQL — see [../operate/multi-server.md](../operate/multi-server.md). |
58
+
| `database is locked` (sqlite) | Concurrent writers / slow disk; sqlite single-writer | Reduce write pressure; move `crowdsec.db` to faster storage; for multi-agent or high volume switch the backend to PostgreSQL — see [../operate/multi-server.md](../../operate/multi-server.md). |
59
59
| sqlite errors + `df` shows full `/var/lib/crowdsec` | Disk full → silent alert-write failure | Free space / rotate; alerts resume. |
60
60
61
61
## Hub
@@ -69,10 +69,10 @@ Match the error string the engine/bouncer printed to the row below.
69
69
70
70
| Symptom | Likely cause | Confirm |
71
71
|---|---|---|
72
-
| Expected ban "not happening"for an IP | The IP matches an **allowlist**|`cscli allowlists check <ip>` → [../configure/allowlists.md](../configure/allowlists.md). |
73
-
| Decision exists, traffic still passes | Bouncer latency / scope / key / IP family | Full ladder: [bouncer-not-blocking.md](./bouncer-not-blocking.md). |
72
+
| Expected ban "not happening" for an IP | The IP matches an **allowlist** | `cscli allowlists check <ip>` → [../../configure/allowlists.md](../../configure/allowlists.md). |
73
+
| Decision exists, traffic still passes | Bouncer latency / scope / key / IP family | Full ladder: [not-blocked.md](../symptoms/not-blocked.md). |
74
74
75
75
When the string isn't here, capture the full forensic bundle with
76
-
[`scripts/diagnose.sh`](../../scripts/diagnose.sh) and read the agent log around
76
+
[`scripts/diagnose.sh`](../../../scripts/diagnose.sh) and read the agent log around
77
77
the first `level=error`/`FATAL` — the *first* error is usually the root cause;
0 commit comments