diff --git a/.gitignore b/.gitignore index 3a76f31..1b25b5f 100644 --- a/.gitignore +++ b/.gitignore @@ -128,3 +128,7 @@ dist .yarn/install-state.gz .pnp.* .omx/ + +# ios build files +mobile/ios/App/App.xcworkspace/contents.xcworkspacedata +mobile/ios/App/Podfile.lock diff --git a/docs/content/docs/api/overview.mdx b/docs/content/docs/api/overview.mdx index 9d315e3..735d30a 100644 --- a/docs/content/docs/api/overview.mdx +++ b/docs/content/docs/api/overview.mdx @@ -25,7 +25,7 @@ Responses are generally returned in JSON format. ```json { - "status": "success", + "success": true, "data": { ... } } ``` @@ -34,7 +34,7 @@ Responses are generally returned in JSON format. ```json { - "status": "error", - "message": "Error description" + "success": false, + "error": "Error description" } ``` diff --git a/docs/content/docs/development/architecture.mdx b/docs/content/docs/development/architecture.mdx index 29fed1d..e67c750 100644 --- a/docs/content/docs/development/architecture.mdx +++ b/docs/content/docs/development/architecture.mdx @@ -10,7 +10,7 @@ CrowdSec Manager is built as a monolithic application with a clear separation be ## Backend (Go) The backend is written in Go and handles: -- **API Server**: Exposes REST endpoints using `chi` router. +- **API Server**: Exposes REST endpoints using `gin-gonic/gin` router. - **Docker Integration**: Communicates with the Docker daemon via the Docker SDK. - **Database**: Uses SQLite for storing configuration and state. - **Background Jobs**: Runs cron jobs for backups and maintenance. diff --git a/docs/content/docs/development/contributing.mdx b/docs/content/docs/development/contributing.mdx index 8c25432..e94889d 100644 --- a/docs/content/docs/development/contributing.mdx +++ b/docs/content/docs/development/contributing.mdx @@ -15,7 +15,7 @@ We welcome contributions to CrowdSec Manager! ``` 2. **Install dependencies**: - - Go 1.21+ + - Go 1.23+ - Node.js 18+ - Docker diff --git a/docs/content/docs/features/config-validation.mdx b/docs/content/docs/features/config-validation.mdx new file mode 100644 index 0000000..69b857d --- /dev/null +++ b/docs/content/docs/features/config-validation.mdx @@ -0,0 +1,76 @@ +--- +title: Config Validation +description: Detect drift between running config and saved snapshots +--- + +# Config Validation + +The Config Validation feature allows you to detect configuration drift between the current running configuration of CrowdSec Manager and saved configuration snapshots. This helps ensure consistency and identify unintended changes. + +## Features + +- **Configuration Drift Detection**: Compare running configuration against saved snapshots +- **Snapshot Management**: Create, list, and restore configuration snapshots +- **Detailed Diff Reports**: View specific differences between configurations +- **Automated Validation**: Schedule regular configuration validation checks + +## API Endpoints + +The Config Validation exposes the following API endpoints under the `/api/config-validation` prefix: + +### Snapshots + +- `POST /config-validation/snapshot` - Create a new configuration snapshot +- `GET /config-validation/snapshots` - List all saved configuration snapshots +- `GET /config-validation/snapshot/:id` - Get details of a specific snapshot +- `DELETE /config-validation/snapshot/:id` - Delete a configuration snapshot + +### Validation + +- `POST /config-validation/validate` - Validate current configuration against a snapshot +- `GET /config-validation/validation/:id` - Get results of a specific validation +- `GET /config-validation/validations` - List all validation results + +### Restoration + +- `POST /config-validation/restore/:id` - Restore configuration from a snapshot + +## Usage Examples + +### Creating a Snapshot + +```bash +curl -X POST http://localhost:8080/api/config-validation/snapshot \ + -H "Content-Type: application/json" \ + -d '{ + "name": "pre-update-backup", + "description": "Backup before applying security updates" + }' +``` + +### Validating Configuration + +```bash +curl -X POST http://localhost:8080/api/config-validation/validate \ + -H "Content-Type: application/json" \ + -d '{ + "snapshot_id": "abc123", + "check_items": ["api_config", "database_config", "docker_settings"] + }' +``` + +### Restoring from Snapshot + +```bash +curl -X POST http://localhost:8080/api/config-validation/restore/abc123 +``` + +## Configuration + +Config validation behavior can be customized through environment variables or the configuration file. Refer to the [Configuration](../configuration/index.mdx) documentation for details. + +## Related Topics + +- [Configuration](../configuration/index.mdx) +- [Backup and Restore](../features/backups.mdx) +- [History](../features/history.mdx) \ No newline at end of file diff --git a/docs/content/docs/features/history.mdx b/docs/content/docs/features/history.mdx new file mode 100644 index 0000000..38f92ae --- /dev/null +++ b/docs/content/docs/features/history.mdx @@ -0,0 +1,93 @@ +--- +title: History +description: Decision history with trends, charts, geographic data +--- + +# History + +The History feature provides persistent storage and analysis of CrowdSec decisions and alerts over time. This enables you to track security events, identify trends, and generate reports for compliance and auditing purposes. + +## Features + +- **Decision History**: Persistent storage of all bans, captchas, and other decisions made by CrowdSec. +- **Alert History**: Complete history of alerts generated by CrowdSec scenarios. +- **Trend Analysis**: Visualize security event trends over time with charts and graphs. +- **Geographic Data**: View the geographic origin of attacks on a world map. +- **Repeated Offenders**: Identify IP addresses that repeatedly trigger security events. +- **Configurable Retention**: Set how long history data is stored before automatic cleanup. +- **Reapply Decisions**: Re-insert historical decisions back into CrowdSec for immediate effect. +- **Bulk Operations**: Reapply multiple historical decisions at once. + +## API Endpoints + +The History exposes the following API endpoints under the `/api` prefix: + +### Decision History + +- `GET /crowdsec/decisions/history` - Retrieve persisted decision history with filtering options. +- `POST /crowdsec/decisions/history/reapply` - Re-insert a historical decision into CrowdSec. +- `POST /crowdsec/decisions/history/bulk-reapply` - Re-insert multiple historical decisions. + +### Alert History + +- `GET /crowdsec/alerts/history` - Retrieve persisted alert history with filtering options. + +### History Statistics + +- `GET /crowdsec/history/stats` - Get aggregate counts for the history dashboard. + +### Configuration + +- `GET /crowdsec/history/config` - Get current history retention configuration. +- `PUT /crowdsec/history/config` - Update history retention configuration. + +### Repeated Offenders + +- `GET /crowdsec/decisions/repeated-offenders` - Get list of repeated offenders from history. + +### Hub Operation History + +- `GET /hub/history` - List hub operation history with filtering options. +- `GET /hub/history/:id` - Get details of a specific hub operation. + +## Usage Examples + +### Retrieving Decision History + +```bash +curl "http://localhost:8080/api/crowdsec/decisions/history?limit=100&scenario=crowdsecurity/ssh-bf&since=24h" +``` + +### Reapplying a Decision + +```bash +curl -X POST http://localhost:8080/api/crowdsec/decisions/history/reapply \ + -H "Content-Type: application/json" \ + -d '{ + "id": 12345, + "type": "ban", + "duration": "24h", + "reason": "Reapplying due to continued malicious activity" + }' +``` + +### Updating History Retention + +```bash +curl -X PUT http://localhost:8080/api/crowdsec/history/config \ + -H "Content-Type: application/json" \ + -d '{ + "retention_days": 30 + }' +``` + +## Configuration + +History behavior can be customized through environment variables or the configuration file. Refer to the [Configuration](../configuration/index.mdx) documentation for details. + +## Related Topics + +- [Configuration](../configuration/index.mdx) +- [Decisions](../features/decisions.mdx) +- [Alerts](../features/alerts.mdx) +- [Hub Browser](../features/hub.mdx) \ No newline at end of file diff --git a/docs/content/docs/features/hub.mdx b/docs/content/docs/features/hub.mdx new file mode 100644 index 0000000..31016ce --- /dev/null +++ b/docs/content/docs/features/hub.mdx @@ -0,0 +1,86 @@ +--- +title: Hub Browser +description: Browse, install, upgrade CrowdSec collections, parsers, scenarios +--- + +# Hub Browser + +The Hub Browser allows you to manage CrowdSec hub items (collections, parsers, scenarios, postoverflows, etc.) directly from the CrowdSec Manager interface. You can browse available items, install new ones, upgrade existing items, and remove items you no longer need. + +## Features + +- **Browse Hub Items**: View all available hub items by category. +- **Install Items**: Install new hub items from the CrowdSec hub. +- **Upgrade Items**: Upgrade installed hub items to their latest versions. +- **Remove Items**: Remove hub items that are no longer needed. +- **Manual Apply**: Apply custom YAML configurations directly to the CrowdSec container. +- **Preference Management**: Set default behaviors for hub operations per category. +- **Operation History**: Audit all hub operations performed through the manager. + +## API Endpoints + +The Hub Browser exposes the following API endpoints under the `/api/hub` prefix: + +### Categories + +- `GET /hub/categories` - List all supported hub categories with metadata. + +### Items + +- `GET /hub/list` - Legacy endpoint for browsing all hub items (raw format). +- `GET /hub/:category/items` - List hub items for a specific category. +- `POST /hub/:category/install` - Install a hub item in the specified category. +- `POST /hub/:category/remove` - Remove a hub item from the specified category. +- `POST /hub/:category/manual-apply` - Apply a custom YAML file to the CrowdSec container. + +### Preferences + +- `GET /hub/preferences` - Get all hub preferences. +- `GET /hub/preferences/:category` - Get preference for a specific category. +- `PUT /hub/preferences/:category` - Update preference for a specific category. + +### History + +- `GET /hub/history` - List hub operation history with filtering options. +- `GET /hub/history/:id` - Get details of a specific hub operation. + +### Upgrades + +- `POST /hub/upgrade` - Upgrade all hub items to their latest versions. + +## Usage Examples + +### Listing Categories + +```bash +curl http://localhost:8080/api/hub/categories +``` + +### Installing a Scenario + +```bash +curl -X POST http://localhost:8080/api/hub/scenarios/install \ + -H "Content-Type: application/json" \ + -d '{"item_name": "crowdsecurity/ssh-bf"}' +``` + +### Applying Custom YAML + +```bash +curl -X POST http://localhost:8080/api/hub/parsers/manual-apply \ + -H "Content-Type: application/json" \ + -d '{ + "filename": "custom-parser.yaml", + "yaml": "filter: ...", + "target_path": "/etc/crowdsec/parsers/custom-parser.yaml" + }' +``` + +## Configuration + +Hub behavior can be customized through environment variables or the configuration file. Refer to the [Configuration](../configuration/index.mdx) documentation for details. + +## Related Topics + +- [Configuration](../configuration/index.mdx) +- [Backup and Restore](../features/backups.mdx) \ No newline at end of file diff --git a/docs/content/docs/features/multi-host.mdx b/docs/content/docs/features/multi-host.mdx new file mode 100644 index 0000000..5dba290 --- /dev/null +++ b/docs/content/docs/features/multi-host.mdx @@ -0,0 +1,98 @@ +--- +title: Multi-Host Docker +description: Manage multiple Docker hosts (docs say "not available") +--- + +# Multi-Host Docker + +CrowdSec Manager supports managing multiple Docker hosts simultaneously through the `DOCKER_HOSTS` environment variable. This allows you to monitor and control CrowdSec instances running on different Docker daemons from a single CrowdSec Manager interface. + +## Features + +- **Multiple Docker Daemon Management**: Connect to and manage multiple Docker hosts +- **Host-specific Operations**: Perform actions on specific Docker hosts by ID +- **Unified Dashboard**: View combined status and metrics from all connected hosts +- **Failover Support**: Automatic fallback to available hosts when one becomes unreachable +- **Isolated Management**: Each host's CrowdSec instance is managed independently + +## How It Works + +The `DOCKER_HOSTS` environment variable specifies a comma-separated list of Docker host connections in the format `id:endpoint`, where: +- `id` is a unique identifier for the host (used in API calls) +- `endpoint` is the Docker daemon URL (e.g., `unix:///var/run/docker.sock` or `tcp://192.168.1.100:2376`) + +Example: `DOCKER_HOSTS="local:unix:///var/run/docker.sock,remote:tcp://192.168.1.100:2376"` + +## API Endpoints + +Multi-host functionality is primarily accessed through the existing API endpoints with host specification: + +### Host Management + +- `GET /hosts/list` - List all configured Docker hosts and their connection status + +### Host-specific Operations + +Most API endpoints that interact with Docker can be scoped to a specific host using the `host` query parameter: +- `GET /health/stack?host=local` - Check stack health on a specific host +- `GET /crowdsec/decisions?host=remote` - Get decisions from a specific host +- `POST /hub/scenarios/install?host=local` - Install a scenario on a specific host + +## Usage Examples + +### Setting Up Multi-Host + +```bash +# In your .env file or environment +DOCKER_HOSTS="local:unix:///var/run/docker.sock,staging:tcp://staging.example.com:2376,production:tcp://prod.example.com:2376" +``` + +### Checking Host Status + +```bash +curl http://localhost:8080/api/hosts/list +``` + +### Running Host-specific Health Check + +```bash +curl "http://localhost:8080/api/health/stack?host=staging" +``` + +### Installing Hub Item on Specific Host + +```bash +curl -X POST "http://localhost:8080/api/hub/scenarios/install?host=production" \ + -H "Content-Type: application/json" \ + -d '{ + "item_name": "crowdsecurity/ssh-bf" + }' +``` + +## Configuration + +Multi-host Docker is configured exclusively through the `DOCKER_HOSTS` environment variable. No additional configuration is required in CrowdSec Manager. + +### Environment Variable + +- **DOCKER_HOSTS**: Comma-separated list of `id:endpoint` pairs defining Docker hosts to manage + - Format: `id1:endpoint1,id2:endpoint2,...` + - Example: `local:unix:///var/run/docker.sock,remote:tcp://192.168.1.100:2376` + +### Default Behavior + +When `DOCKER_HOSTS` is not set or empty, CrowdSec Manager defaults to using the single Docker host specified by `DOCKER_HOST` (or the default Unix socket). + +## Limitations and Considerations + +- Each Docker host must be accessible from the machine running CrowdSec Manager +- Docker API versions should be compatible across all hosts +- Authentication to Docker daemons (if using TLS) must be configured separately +- Performance may vary based on network latency to remote Docker hosts +- Some operations that require host-level privileges may need additional configuration + +## Related Topics + +- [Configuration](../configuration/index.mdx) +- [Hosts Management](../features/hosts.mdx) *(if separate hosts feature exists)* +- [Terminal](../features/terminal.mdx) (for accessing containers on specific hosts) \ No newline at end of file diff --git a/docs/content/docs/features/simulation.mdx b/docs/content/docs/features/simulation.mdx new file mode 100644 index 0000000..0cd3f24 --- /dev/null +++ b/docs/content/docs/features/simulation.mdx @@ -0,0 +1,75 @@ +--- +title: Simulation Mode +description: Toggle CrowdSec simulation mode from UI +--- + +# Simulation Mode + +CrowdSec Manager allows you to toggle CrowdSec's simulation mode directly from the interface. In simulation mode, CrowdSec will detect and log potential security events but will not apply any actual remediation actions (like banning IP addresses). This is useful for testing new configurations or scenarios without affecting your live traffic. + +## Features + +- **Status Check**: View whether simulation mode is currently enabled or disabled. +- **Toggle Control**: Enable or disable simulation mode for specific scenarios or globally. +- **Scenario-specific Control**: Configure simulation mode on a per-scenario basis. +- **Real-time Feedback**: See the current state and recent changes immediately. + +## API Endpoints + +The Simulation Mode exposes the following API endpoints under the `/api/simulation` prefix: + +### Status + +- `GET /simulation/status` - Get the current simulation status for all scenarios or a specific scenario. + +### Toggle + +- `POST /simulation/toggle` - Enable or disable simulation mode for a specific scenario. + +## Usage Examples + +### Checking Simulation Status + +```bash +curl http://localhost:8080/api/simulation/status +``` + +### Enabling Simulation for a Scenario + +```bash +curl -X POST http://localhost:8080/api/simulation/toggle \ + -H "Content-Type: application/json" \ + -d '{ + "scenario": "crowdsecurity/ssh-bf", + "enabled": true + }' +``` + +### Disabling Simulation for a Scenario + +```bash +curl -X POST http://localhost:8080/api/simulation/toggle \ + -H "Content-Type: application/json" \ + -d '{ + "scenario": "crowdsecurity/ssh-bf", + "enabled": false + }' +``` + +## How Simulation Mode Works + +When simulation mode is enabled for a scenario: +- CrowdSec will still process logs and detect when the scenario would trigger. +- Instead of applying the configured action (ban, captcha, etc.), it will only log the event. +- The event will appear in your alerts and decisions history as if it were applied, but no actual action is taken. +- This allows you to test the effectiveness of scenarios without impacting legitimate traffic. + +## Configuration + +Simulation mode behavior is controlled entirely through the CrowdSec CLI (`cscli`) under the hood. No additional configuration is required in CrowdSec Manager beyond what's exposed via the API. + +## Related Topics + +- [Decisions](../features/decisions.mdx) +- [Hub Browser](../features/hub.mdx) +- [Alerts Analysis](../features/alerts.mdx) \ No newline at end of file diff --git a/docs/content/docs/features/terminal.mdx b/docs/content/docs/features/terminal.mdx new file mode 100644 index 0000000..8c41206 --- /dev/null +++ b/docs/content/docs/features/terminal.mdx @@ -0,0 +1,89 @@ +--- +title: Terminal +description: Web-based shell into the CrowdSec container +--- + +# Terminal + +The Terminal feature provides a web-based interactive shell directly into the CrowdSec container running within CrowdSec Manager. This allows you to execute commands, troubleshoot issues, and perform administrative tasks without needing direct SSH or Docker access to the container. + +## Features + +- **Interactive Shell**: Full-featured terminal access to the CrowdSec container. +- **Multiple Container Support**: Access different containers by specifying the container name. +- **Real-time Output**: See command output as it happens, just like a local terminal. +- **Resize Support**: Terminal automatically adjusts to your browser window size. +- **Secure Connection**: WebSocket-based connection with proper authentication. + +## API Endpoints + +The Terminal exposes the following WebSocket endpoint: + +### WebSocket Connection + +- `GET /terminal/:container` - Establish a WebSocket connection to an interactive terminal in the specified container. + +## Usage Examples + +### Connecting to the CrowdSec Container + +To access the CrowdSec container's terminal through the web interface: + +1. Navigate to the Terminal section in the CrowdSec Manager UI +2. Select "crowdsec" (or your configured container name) from the container dropdown +3. Click "Connect" to establish the terminal session + +### Direct WebSocket Connection (for custom clients) + +```javascript +// Example using JavaScript WebSocket API +const ws = new WebSocket('ws://localhost:8080/terminal/crowdsec'); + +ws.onopen = () => { + console.log('Connected to terminal'); + // Send a command + ws.send('ls -la\n'); +}; + +ws.onmessage = (event) => { + console.log('Received:', event.data); + // Display output in your terminal UI +}; + +ws.onclose = () => { + console.log('Disconnected from terminal'); +}; +``` + +### Available Containers + +You can access different containers by changing the `:container` parameter in the endpoint: +- `crowdsec` - The main CrowdSec Security Engine container +- Other containers defined in your Docker Compose setup (specified via environment variables) + +## How It Works + +The terminal feature uses: +- **WebSocket Protocol**: For real-time, bidirectional communication +- **Docker Exec API**: To create interactive exec sessions in the specified container +- **Pseudo-terminal (PTY)**: To properly handle terminal features like resizing, colors, and interactive programs + +## Security Considerations + +- Terminal access is restricted to the same network access rules as the rest of the API +- Container name validation prevents path traversal and injection attacks +- Each terminal session creates an isolated exec process in the container +- Sessions automatically close when the WebSocket connection is terminated + +## Configuration + +Terminal behavior depends on your Docker configuration. Refer to the [Configuration](../configuration/index.mdx) documentation for details about: +- Container names (`CrowdsecContainerName`) +- Docker host settings (`DOCKER_HOSTS` for multi-host setups) +- General Docker connectivity + +## Related Topics + +- [Configuration](../configuration/index.mdx) +- [Logs Monitoring](../features/logs-monitoring.mdx) +- [Multi-Host Docker](../features/multi-host.mdx) *(if applicable)* \ No newline at end of file