Charon/.github/skills/integration-test-crowdsec-decisions.SKILL.md

name, version, description, author, license, tags, compatibility, requirements, environment_variables, parameters, outputs, metadata

name	version	description	author	license	tags	compatibility	requirements	environment_variables	parameters	outputs	metadata
integration-test-crowdsec-decisions	1.0.0	Test CrowdSec decision API for creating, retrieving, and removing IP blocks	Charon Project	MIT	integration crowdsec decisions api blocking	os shells linux darwin bash	name version optional docker >=24.0 false name version optional curl >=7.0 false name version optional jq >=1.6 false	name description default required CROWDSEC_API_KEY CrowdSec API key for decision management auto-generated false	name type description default required verbose boolean Enable verbose output false false	name type description test_results stdout Decision API test results	category subcategory execution_time risk_level ci_cd_safe requires_network idempotent integration-test api medium medium true true true

Integration Test CrowdSec Decisions

Overview

Tests the CrowdSec decision API functionality for managing IP block decisions. This skill validates decision creation, retrieval, persistence, expiration, and removal through the CrowdSec Local API (LAPI). It ensures the decision lifecycle works correctly and that bouncers receive updates in real-time.

Decisions are the core mechanism CrowdSec uses to communicate threats between detectors and enforcers.

Prerequisites

• Docker 24.0 or higher installed and running
• curl 7.0 or higher for API testing
• jq 1.6 or higher for JSON parsing
• Running CrowdSec LAPI container
• Valid CrowdSec API credentials

Usage

Basic Usage

Run CrowdSec decision API tests:

cd /path/to/charon
.github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions

Verbose Mode

Run with detailed API request/response logging:

VERBOSE=1 .github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions

CI/CD Integration

For use in GitHub Actions workflows:

- name: Test CrowdSec Decision API
  run: .github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions
  timeout-minutes: 5

Parameters

Parameter	Type	Required	Default	Description
verbose	boolean	No	false	Enable verbose output

Environment Variables

Variable	Required	Default	Description
CROWDSEC_API_KEY	No	auto	API key for LAPI access
CROWDSEC_LAPI_URL	No	http://crowdsec:8080	CrowdSec LAPI endpoint
TEST_IP	No	192.0.2.1	Test IP address for decisions

Outputs

Success Exit Code

• 0: All decision API tests passed

Error Exit Codes

• 1: One or more tests failed
• 2: LAPI not accessible
• 3: Authentication failed
• 4: Decision creation/deletion failed

Console Output

Example output:

=== Testing CrowdSec Decision API ===
✓ Create Decision: IP 192.0.2.1 blocked for 4h
✓ Retrieve Decisions: 1 active decision found
✓ Decision Details: Correct scope, value, duration
✓ Decision Persistence: Survives bouncer restart
✓ Decision Expiration: Expires after duration
✓ Remove Decision: Successfully deleted
✓ Decision Cleanup: No orphaned decisions

All CrowdSec decision API tests passed!

Test Coverage

This skill validates:

1. Decision Creation:

   • Create IP ban decision via API
   • Create range ban decision
   • Create captcha decision
   • Set custom duration and reason

2. Decision Retrieval:

   • List all active decisions
   • Filter by scope (ip, range, country)
   • Filter by value (specific IP)
   • Pagination support

3. Decision Persistence:

   • Decisions survive LAPI restart
   • Decisions sync to bouncers
   • Database integrity

4. Decision Lifecycle:

   • Expiration after duration
   • Manual removal via API
   • Automatic cleanup of expired decisions

5. Decision Synchronization:

   • Bouncer receives new decisions
   • Bouncer updates on decision changes
   • Real-time propagation

Examples

Example 1: Basic Execution

.github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions

Example 2: Test Specific IP

TEST_IP=10.0.0.1 \
  .github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions

Example 3: Custom LAPI URL

CROWDSEC_LAPI_URL=https://crowdsec-lapi.example.com \
  .github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions

Example 4: Verbose with API Key

CROWDSEC_API_KEY=my-api-key VERBOSE=1 \
  .github/skills/scripts/skill-runner.sh integration-test-crowdsec-decisions

API Endpoints Tested

• POST /v1/decisions - Create new decision
• GET /v1/decisions - List decisions
• GET /v1/decisions/:id - Get decision details
• DELETE /v1/decisions/:id - Remove decision
• GET /v1/decisions/stream - Bouncer decision stream

Error Handling

Common Errors

Error: LAPI not responding

Solution: Check LAPI container: docker ps | grep crowdsec

Error: Authentication failed

Solution: Verify API key: docker exec crowdsec cscli machines list

Error: Decision not created

Solution: Check LAPI logs for validation errors

Error: Decision not found after creation

Solution: Verify database connectivity and permissions

Debugging

• LAPI Logs: docker logs $(docker ps -q -f name=crowdsec)
• Database: docker exec crowdsec cscli decisions list
• API Testing: curl -H "X-Api-Key: $KEY" http://localhost:8080/v1/decisions
• Decision Details: docker exec crowdsec cscli decisions list -o json | jq

Related Skills

• integration-test-crowdsec - Main bouncer tests
• integration-test-crowdsec-startup - Startup tests
• integration-test-all - Complete suite

Notes

• Execution Time: Medium execution (3-5 minutes)
• Decision Types: Supports ban, captcha, and throttle decisions
• Scopes: IP, range, country, AS, user
• Duration: From seconds to permanent bans
• API Version: Tests LAPI v1 endpoints
• Cleanup: All test decisions are removed after execution
• Idempotency: Safe to run multiple times
• Isolation: Uses test IP ranges (RFC 5737)

---

Last Updated: 2025-12-20 Maintained by: Charon Project Team Source: scripts/crowdsec_decision_integration.sh