|
1 | | -### CrowdSec Scenario Deployment Helper |
| 1 | +# CrowdSec Scenario Deployment Assistant |
2 | 2 |
|
3 | | -Use this checklist to package, publish, and roll out a new CrowdSec scenario safely. |
| 3 | +Provide an interactive deployment experience for validated CrowdSec scenarios. |
4 | 4 |
|
5 | | -**Preflight** |
6 | | -- Confirm the scenario YAML validates against the official schema. |
7 | | -- Ensure associated parsers, collections, and data files are already published or bundled. |
8 | | -- Document expected labels (`service`, `behavior`, `classification`) for downstream consumers. |
| 5 | +## Step 1: Prerequisites Check |
9 | 6 |
|
10 | | -**Local Packaging** |
11 | | -- Create or update a collection under `hub/collections/` with your scenario in `scenarios/`. |
12 | | -- Run `cscli lint` on the collection to verify metadata, dependency graph, and manifest. |
13 | | -- Execute `cscli hubtest run <collection>` or tailored replay tests before shipping. |
| 7 | +Ask: "Do you have CrowdSec already installed and running?" |
14 | 8 |
|
15 | | -**Versioning & Metadata** |
16 | | -- Bump the collection `version` and add a concise changelog entry. |
17 | | -- Update `description`, `author`, and `tags` to reflect the new detection surface. |
18 | | -- Include `references` or `data` source URLs when external threat intel is consumed. |
| 9 | +- **YES**: Continue to Step 2 |
| 10 | +- **NO**: Direct them to: https://doc.crowdsec.net/docs/getting_started/install_crowdsec |
19 | 11 |
|
20 | | -**Distribution** |
21 | | -- For private rollouts: publish to an internal mirror via `cscli hub push --url <repo>`. |
22 | | -- For community sharing: open a PR against the public CrowdSec hub with scenario, collection, and documentation updates. |
23 | | -- Communicate migration guidance (e.g., new labels, breaking filter changes) to operators. |
| 12 | +## Step 2: Scenario Source & Packaging |
24 | 13 |
|
25 | | -**Post-Deployment** |
26 | | -- Monitor `cscli decisions list` and alerting channels for noise or missed detections. |
27 | | -- Gather feedback and iterate quickly; update the scenario or collection version as needed. |
| 14 | +Ask: "Is this a custom scenario you maintain locally, or are you trying to install something from the Hub?" |
| 15 | + |
| 16 | +- **HUB SCENARIO**: Explain that hub scenarios should be installed via collections (`cscli collections install <collection>`), per https://doc.crowdsec.net/docs/log_processor/scenarios/deploy. Offer to switch to installation guidance if needed. |
| 17 | +- **CUSTOM SCENARIO**: Collect the deployment inputs: |
| 18 | + 1. The local path to the scenario YAML ready to copy into `/etc/crowdsec/scenarios/`. |
| 19 | + 2. Confirmation that dependencies (parsers, enrichers, post-overflows) are present or provide commands to install them. |
| 20 | + 3. Optional: proof of validation (eg. `cscli hubtest run` output or sample logs). |
| 21 | + After gathering this data, proceed to Step 3. |
| 22 | + |
| 23 | +## Step 3: Deployment |
| 24 | + |
| 25 | +Instruct the user to: |
| 26 | +- deploy his yaml file in `/etc/crowdsec/scenarios/`. |
| 27 | +- verify deployment with `cscli` |
| 28 | + |
| 29 | + |
| 30 | +## Command Templates |
| 31 | + |
| 32 | +### For Step 3 (Existing Setup): |
| 33 | + |
| 34 | +Use user's existing paths and add scenario to existing directory. |
| 35 | + |
| 36 | +#### Host based Installation: |
| 37 | + |
| 38 | +# Install the scenario file |
| 39 | +```bash |
| 40 | +sudo install -m 644 ./SCENARIO_NAME.yaml /etc/crowdsec/scenarios/custom/SCENARIO_NAME.yaml |
| 41 | +``` |
| 42 | + |
| 43 | +#### Container Installation: |
| 44 | +```bash |
| 45 | +# Copy scenario file to container |
| 46 | +docker cp ./SCENARIO_NAME.yaml crowdsec_container:/etc/crowdsec/scenarios/custom/ |
| 47 | + |
| 48 | +# Install required collections (if not already present) |
| 49 | +docker exec crowdsec_container cscli collections install COLLECTION_NAME |
| 50 | +``` |
| 51 | + |
| 52 | +## Final Steps (Both Paths) |
| 53 | + |
| 54 | +### Native Installation: |
| 55 | +```bash |
| 56 | +# Reload CrowdSec to apply changes |
| 57 | +sudo systemctl reload crowdsec |
| 58 | + |
| 59 | +# Verify scenario is loaded |
| 60 | +sudo cscli scenarios list | grep SCENARIO_NAME |
| 61 | + |
| 62 | +# Check scenario metrics |
| 63 | +sudo cscli metrics |
| 64 | +``` |
| 65 | + |
| 66 | +### Container Installation: |
| 67 | +```bash |
| 68 | +# Reload CrowdSec to apply changes |
| 69 | +docker exec crowdsec_container kill -HUP 1 |
| 70 | + |
| 71 | +# Verify scenario is loaded |
| 72 | +docker exec crowdsec_container cscli scenarios list | grep SCENARIO_NAME |
| 73 | + |
| 74 | +# Check scenario metrics |
| 75 | +docker exec crowdsec_container cscli metrics |
| 76 | +``` |
0 commit comments