diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..215f709 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,69 @@ +name: Bug report +description: Something in the skill is wrong, stale, or doesn't work +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + This tracker is for the **skill** — its instructions, reference docs, and packaging. + For problems with CrowdSec itself, open an issue on + [crowdsecurity/crowdsec](https://github.com/crowdsecurity/crowdsec/issues). + + - type: input + id: area + attributes: + label: Area + description: Which part of the skill. Free text — a path, a feature, or a rough description. + placeholder: install · configure · bouncers · WAF/AppSec · operate · debug · migrate · service-api · packaging + validations: + required: true + + - type: input + id: doc + attributes: + label: Which file? + description: Path to the reference doc, if you know it. + placeholder: skills/crowdsec/references/install/docker.md + validations: + required: false + + - type: textarea + id: what + attributes: + label: What happened + description: What the skill told you to do, and what actually happened. + validations: + required: true + + - type: textarea + id: expected + attributes: + label: What should have happened + validations: + required: true + + - type: input + id: env + attributes: + label: Environment + description: Where you ran it. + placeholder: bare-metal/systemd · Docker · Kubernetes/Helm · pfSense/OPNsense · not environment-specific + validations: + required: true + + - type: input + id: version + attributes: + label: CrowdSec version + description: Output of `cscli version`, if relevant. + placeholder: "1.8.1" + validations: + required: false + + - type: input + id: agent + attributes: + label: Agent + placeholder: Claude Code 2.x / Codex / Claude.ai web + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6e24d6a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: true +contact_links: + - name: CrowdSec itself (engine, cscli, bouncers) + url: https://github.com/crowdsecurity/crowdsec/issues + about: Bugs in CrowdSec rather than in this skill. + - name: CrowdSec documentation + url: https://docs.crowdsec.net + about: Canonical docs the reference files derive from. + - name: Community Discord + url: https://discord.com/invite/crowdsec + about: Questions and help with your setup. + - name: Security vulnerability + url: https://github.com/crowdsecurity/crowdsec/security/policy + about: Report privately to security@crowdsec.net — never as a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..4d873ed --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,55 @@ +name: Coverage request +description: Ask for a new environment, bouncer, or workflow to be covered +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + This skill is **operational** — it deploys, configures, and debugs CrowdSec. It does + not author detection content; parsers, scenarios, and WAF rules belong in the + [CrowdSec Hub](https://hub.crowdsec.net). + + - type: input + id: area + attributes: + label: Area + description: Which part of the skill this lands in. Free text. + placeholder: install · configure · bouncers · WAF/AppSec · operate · debug · migrate · service-api + validations: + required: true + + - type: textarea + id: request + attributes: + label: What should the skill be able to do? + description: The task you want to hand to your agent, in the words you'd use. + placeholder: '"Deploy CrowdSec on my Synology NAS and wire the firewall bouncer."' + validations: + required: true + + - type: textarea + id: why + attributes: + label: Why isn't it covered today? + description: What the skill does instead — wrong answer, no answer, or partial. + validations: + required: true + + - type: input + id: docs + attributes: + label: Canonical docs + description: Upstream CrowdSec documentation for this, if it exists. + placeholder: https://docs.crowdsec.net/docs/... + validations: + required: false + + - type: textarea + id: verify + attributes: + label: Can you test it? + description: | + Nothing ships unverified — every recipe must be run against a real environment first. + Say whether you have this environment and could verify a PR against it. + validations: + required: false diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e23001..a088443 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 test), `configure.md` (the `challenge:` block, multi-instance `master_secret`, difficulty levels), `customize.md` (hook/helper matrix, exemptions, `MatchKnownBot` datafiles, fingerprint scoring, custom scenarios), `troubleshoot.md` (10 symptoms + metrics reading). +- `CONTRIBUTING.md` and `.github/ISSUE_TEMPLATE/` (bug report, coverage request, + routing config). +- `README.md` — **Reference docs** index linking each `references/` area. ### Changed - `SKILL.md` — bot-detection routing rows, boundary row, trigger phrases in `description`, @@ -22,10 +25,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `references/appsec/{overview,configure,deploy,troubleshoot}.md` — `challenge` action, `on_challenge` / `on_challenge_submit` hooks, and pointers into `bot-detection/`. - `references/configure/bouncers/web-servers.md` — per-bouncer bot-detection capability column. +- `README.md` — title and opening rewritten to state what the plugin is and which agents it + targets; version badge now reads `plugin.json` at render time; emoji removed from headings + so anchors are stable; marketplace/plugin/skill naming stated explicitly. +- `CLAUDE.md` — `install/` layout row lists `pfsense.md`. ### Fixed - `references/install/console.md` — `cscli console enroll` enables `manual` and `context` (with `tainted`); the `share_*` false defaults only apply to never-enrolled engines. +- `README.md` — Install row said OpnSense; the install doc covers pfSense. OPNsense/FreeBSD + is covered under `configure/` and `appsec/`, not `install/`. +- `README.md` — doc link pointed at `doc.crowdsec.net`; now `docs.crowdsec.net` throughout. ## [0.2.3] - 2026-05-29 diff --git a/CLAUDE.md b/CLAUDE.md index 5fdc0c2..a9217bd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,7 +49,7 @@ All depth lives in `references//`, organized by the axis that fits the are | Dir | Organized by | Notes | |---|---|---| -| `install/` | **platform** (one file each) | `bare-metal.md` (apt/dnf + systemd), `docker.md`, `kubernetes.md`, `console.md` (enrollment) — install mechanics genuinely diverge per platform. | +| `install/` | **platform** (one file each) | `bare-metal.md` (apt/dnf + systemd), `docker.md`, `kubernetes.md`, `pfsense.md`, `console.md` (enrollment) — install mechanics genuinely diverge per platform. | | `configure/` | **config domain** | `acquisition`, `hub`, `profiles`, `notifications`, `allowlists`; platforms merged inline. `configure/bouncers/` nests one level by **service type** (`firewall`, `web-servers`). | | `operate/` | **task** | `health-check`, `upgrades`, `multi-server`. | | `appsec/` | **lifecycle** | `overview` → `deploy` → `configure` → `troubleshoot` (the WAF/AppSec feature silo). | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4877640 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,60 @@ +# Contributing + +Issues and PRs are welcome. Improvements to the reference docs and coverage for new +environments are the most useful contributions. + +## Before you open a PR + +Authoring conventions for this skill live in [CLAUDE.md](CLAUDE.md) — writing style, +directory layout, version gating, and the `verified:` frontmatter block. Read it before +adding or restructuring a reference doc; it is the authoritative map of where content goes. + +The rule that matters most: + +> **Nothing ships unverified.** Every command and expected outcome must have been run +> against a real, current CrowdSec environment and observed first-hand — not inferred, +> not recalled. If you cannot verify something, mark it `untested` or leave it out. + +Verification is recorded per file in a `verified:` block (date, engine version, environment). +When you run a doc's commands and see them work, stamp it in the same change. + +## What CI checks + +`.github/workflows/validate.yml` runs on every PR: + +| Check | Fails the build? | +|---|---| +| `plugin.json` and `marketplace.json` versions agree | yes | +| `claude plugin validate .` | yes | +| Malformed `verified:` frontmatter | yes | +| Missing or stale (>180 days) verification records | no — informational | + +Run the verification report locally with: + +```bash +python3 skills/crowdsec/scripts/check-verification.py +``` + +## Scope + +This is an **operational** skill: install, configure, operate, debug. Authoring detection +content — parsers, scenarios, WAF rules — is out of scope and belongs in the +[CrowdSec Hub](https://hub.crowdsec.net). + +## Testing changes + +The local working copy is for static checks only. Run commands that change or inspect a +CrowdSec install against a dedicated test environment, never against your authoring machine. + +## Commits and PRs + +- Conventional commits, one-line subject where possible (`fix(console): …`, `docs(readme): …`). +- Keep PR descriptions short — what changed and why, not a narrative. +- Update [CHANGELOG.md](CHANGELOG.md) under `[Unreleased]` in the same change. + +## Reporting a problem + +Open an issue using one of the [templates](.github/ISSUE_TEMPLATE/). For anything +security-sensitive in CrowdSec itself, follow the +[CrowdSec security policy](https://github.com/crowdsecurity/crowdsec/security/policy) +rather than filing a public issue here. diff --git a/README.md b/README.md index 7cd23c3..c486525 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,15 @@ CrowdSec -# CrowdSec skills +# CrowdSec Skill for Claude Code & Codex -**Install, configure, operate, and debug [CrowdSec](https://doc.crowdsec.net) — straight from your terminal, with your coding agent doing the heavy lifting.** +**The official CrowdSec plugin for AI coding agents.** It bundles two +[Agent Skills](https://docs.claude.com/en/docs/claude-code/skills) that let Claude Code, +Codex, and Claude.ai install, configure, operate, and debug +[CrowdSec](https://docs.crowdsec.net) — the engine, `cscli`, bouncers, and the WAF/AppSec +component — across bare-metal/systemd, Docker, pfSense/OPNsense, and Kubernetes/Helm. -[![Version](https://img.shields.io/badge/version-0.2.3-blue)](.claude-plugin/plugin.json) +[![Version](https://img.shields.io/badge/dynamic/json?label=version&query=%24.version&url=https%3A%2F%2Fraw.githubusercontent.com%2Fcrowdsecurity%2Fcrowdsec-skill%2Fmain%2F.claude-plugin%2Fplugin.json&color=blue)](.claude-plugin/plugin.json) [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE) [![Agent Skills](https://img.shields.io/badge/Agent-Skills-8A2BE2)](https://docs.claude.com/en/docs/claude-code/skills) [![CrowdSec](https://img.shields.io/badge/CrowdSec-docs-orange)](https://docs.crowdsec.net) @@ -20,7 +24,7 @@ This plugin bundles **two [Agent Skills](https://docs.claude.com/en/docs/claude- - **`crowdsec`** — a hands-on CrowdSec operator. Stand up an engine, wire a bouncer, enable the WAF, or figure out why nothing's getting blocked. It knows the `cscli` commands, the config layout, the failure modes, and the safe way - through each across **bare-metal/systemd, Docker, OpnSense and Kubernetes/Helm**. + through each across **bare-metal/systemd, Docker, pfSense/OPNsense and Kubernetes/Helm**. - **`crowdsec-service-api`** — drives the premium **Console Service API** (cloud) on your behalf with your API key: create and populate blocklists/allowlists, wire firewall/appliance integrations, pull remediation ROI metrics, and manage @@ -33,9 +37,9 @@ This plugin bundles **two [Agent Skills](https://docs.claude.com/en/docs/claude- | Area | Covered | |---|---| -| **Install** | bare-metal/systemd · Docker · Kubernetes/Helm · OpnSense · Console enrollment | +| **Install** | bare-metal/systemd · Docker · Kubernetes/Helm · pfSense/OPNsense · Console enrollment | | **Bouncers** | firewall (iptables/nftables/ipset) · nginx · traefik · caddy · apache · and more | -| **WAF / AppSec** | deploy · configure · troubleshoot the AppSec component | +| **WAF / AppSec** | deploy · configure · troubleshoot the AppSec component · bot detection | | **Hub** | install collections/parsers/scenarios · update · debug | | **Configure** | acquisition · profiles & ban durations · notifications · allowlists | | **Operate** | health checks & smoke tests · upgrades & rollback · multi-server / remote LAPI / mTLS | @@ -51,11 +55,14 @@ This plugin bundles **two [Agent Skills](https://docs.claude.com/en/docs/claude- | **Metrics** | remediation ROI (traffic dropped, bytes/egress saved, attacks prevented) | | **Decisions** | org-level decisions + aggregated (read/manage) | -## 🚀 Install +## Install The skill loads automatically once installed. Just talk to your agent about CrowdSec. +> **Naming:** the marketplace is `crowdsecurity`, the plugin inside it is `crowdsec`, +> and the plugin ships two skills — `crowdsec` and `crowdsec-service-api`. + **On Claude Code** ```text @@ -87,7 +94,7 @@ and upload it in the web skill uploader. npx skills add crowdsecurity/crowdsec-skill ``` -## 💬 Example prompts +## Example prompts Once installed, the agent picks the skill up whenever your prompt involves CrowdSec: @@ -101,7 +108,7 @@ Once installed, the agent picks the skill up whenever your prompt involves Crowd - _"Wire a Palo Alto external dynamic list to my CrowdSec blocklist."_ (Service API) - _"Show me the remediation ROI metrics for last month."_ (Service API) -## What it does **not** do +## What this skill does not do This is an **operational** skill. It deploys, configures, and debugs CrowdSec — it does **not author** detection content. Writing a parser, scenario, or WAF @@ -110,18 +117,34 @@ it does **not author** detection content. Writing a parser, scenario, or WAF For authoring, head to the [CrowdSec Hub](https://hub.crowdsec.net) and the [detection-engineering docs](https://docs.crowdsec.net/docs/next/local_api/intro). -## 🤝 Contributing +## Reference docs + +Both skills are backed by 37 reference documents, each verified against a real CrowdSec +environment before it ships: + +| Area | Covers | +|---|---| +| [`install/`](skills/crowdsec/references/install/) | bare-metal · Docker · Kubernetes · pfSense · Console enrollment | +| [`configure/`](skills/crowdsec/references/configure/) | acquisition · hub · profiles · notifications · allowlists · [bouncers](skills/crowdsec/references/configure/bouncers/) | +| [`appsec/`](skills/crowdsec/references/appsec/) | WAF deploy · configure · troubleshoot · [bot detection](skills/crowdsec/references/appsec/bot-detection/) | +| [`operate/`](skills/crowdsec/references/operate/) | health checks · upgrades · multi-server | +| [`debug/`](skills/crowdsec/references/debug/) | [common](skills/crowdsec/references/debug/common/) errors & triage · [symptoms](skills/crowdsec/references/debug/symptoms/): parsing, no alerts, not blocked | +| [`migrate/`](skills/crowdsec/references/migrate/) | [from fail2ban](skills/crowdsec/references/migrate/from-fail2ban.md) | +| [Service API](skills/crowdsec-service-api/references/) | authentication · blocklists · allowlists · integrations · metrics · decisions | + +## Contributing -Issues and PRs welcome. Improvements to the reference docs and new environment -coverage are appreciated. If you see anything missing or wrong, don't hesitate to open a PR. +Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Improvements to the +reference docs and new environment coverage are especially appreciated. If you see +anything missing or wrong, don't hesitate to open a PR. -## 🔗 Links +## Links - CrowdSec: - Documentation: - Hub: - Console: -## 📄 License +## License MIT — see [LICENSE](LICENSE).