Documentation

v0.4.12 // Command Reference & Guides

Getting Started

1-SEC deploys as a single binary. No dependencies, no containers required for basic operation. All 16 modules are enabled by default with sane defaults — zero-config works out of the box.

Install & Run

# Download the latest release
curl -fsSL https://1-sec.dev/get | sh

# Or build from source
git clone https://github.com/cutmob/1-SEC.git
cd 1-SEC && go build ./cmd/1sec/

# Guided setup (config + AI keys + API auth in one flow)
1sec setup

# Or start all modules with defaults (zero-config)
1sec up

# Start with a custom config file
1sec up --config /path/to/config.yaml

CLI Reference

Global Flags

Most commands that talk to a running instance accept these common flags:--host,--port,--api-key,--timeout,--profile,--config. These can also be set via environment variables:ONESEC_HOST,ONESEC_PORT,ONESEC_API_KEY,ONESEC_CONFIG,ONESEC_PROFILE.

1sec up

Start the 1-SEC engine with all enabled modules.

# Start with default config (configs/default.yaml)
1sec up

# Start with custom config
1sec up --config /path/to/config.yaml

# Start only specific modules (disables all others)
1sec up --modules injection_shield,auth_fortress,network_guardian

# Override log level
1sec up --log-level debug

# Validate config and modules without starting
1sec up --dry-run

# Suppress banner and non-essential output
1sec up --quiet

# Disable color output
1sec up --no-color

1sec status

Fetch and display the running engine status (version, modules, alerts, bus connection).

1sec status

# Output:
# ● 1-SEC Status
#
#   Version:           1.0.0
#   Status:            running
#   Bus Connected:     true
#   Modules Active:    16
#   Total Alerts:      42
#   Rust Engine:       running
#   Enforcement:       dry-run (safe)
#
#   Modules:
#     ● network_guardian         DDoS mitigation, rate limiting...
#     ● injection_shield         SQLi, XSS, SSRF detection...
#     ...

# Output as JSON
1sec status --json

# Output as CSV
1sec status --format csv

# Save to file
1sec status --json --output status.json

# Custom host/port
1sec status --host 10.0.0.5 --port 1780

# Use a named profile
1sec status --profile prod

1sec modules

List, inspect, enable, or disable defense modules. Supports tier filtering and multiple output formats.

# List all 16 modules
1sec modules

# Filter by tier
1sec modules --tier 2

# Output as JSON or CSV
1sec modules --json
1sec modules --format csv

# Show detailed info for a specific module
1sec modules info injection_shield
1sec modules info llm_firewall --json

# Enable or disable a module in the config
1sec modules enable iot_shield
1sec modules disable deepfake_shield

1sec version

Print the current version.

1sec version
# 1-SEC v0.4.12

1sec alerts

Fetch, acknowledge, resolve, or manage alerts from a running 1-SEC instance.

# Fetch all recent alerts
1sec alerts

# Filter by severity
1sec alerts --severity CRITICAL

# Filter by module and status
1sec alerts --severity HIGH --module injection_shield --status OPEN

# Output as JSON, save to file
1sec alerts --severity CRITICAL --json --output alerts.json

# Limit results
1sec alerts --limit 50

# Get a specific alert by ID
1sec alerts get a-29f1c...

# Acknowledge an alert
1sec alerts ack a-29f1c...

# Resolve an alert
1sec alerts resolve a-29f1c...

# Mark as false positive
1sec alerts false-positive a-29f1c...

# Delete a single alert
1sec alerts delete a-29f1c...

# Clear all alerts
1sec alerts clear
1sec alerts clear --confirm

1sec scan

Submit a payload for on-demand analysis. Reads from stdin or a file.

# Scan for SQL injection
echo '{"query": "1 OR 1=1"}' | 1sec scan --module injection_shield

# Scan a file for prompt injection
1sec scan --input payload.json --module llm_firewall --type prompt_check

# Pipe from curl
curl -s https://example.com/api | 1sec scan --module api_fortress

# Wait for analysis results (polls for alerts)
1sec scan --input payload.json --module injection_shield --wait

# Wait with custom timeout
1sec scan --input payload.json --wait --wait-timeout 60s

# Set severity and output as JSON
1sec scan --input payload.json --severity HIGH --json

1sec config

Show, validate, or modify the fully resolved configuration.

# Show resolved config
1sec config

# Validate config and exit
1sec config --validate

# Output as JSON
1sec config --json

# Set a config value
1sec config set logging.level debug
1sec config set modules.iot_shield.enabled false

# Set Gemini API key (shortcut)
1sec config set-key AIzaSy...
1sec config set-key --show

1sec check

Run pre-flight diagnostics to verify the system is ready.

1sec check

# Checks performed:
#   ✓ Config file is valid and loadable
#   ✓ API port 1780 is available
#   ✓ NATS port 4222 is available
#   ✓ Data directory is writable
#   ✓ AI API keys configured (if AI engine enabled)
#   ✓ No port conflicts (API vs NATS vs Syslog)
#   ✓ Rust engine binary found (if enabled)

# Output as JSON
1sec check --json

# Use a named profile
1sec check --profile prod

1sec stop

Gracefully stop a running 1-SEC instance via the API.

# Stop the running instance
1sec stop

# Stop with custom host/port
1sec stop --host 10.0.0.5 --port 1780

1sec docker

Manage the 1-SEC Docker Compose deployment without leaving the CLI.

# Start via Docker Compose (detached)
1sec docker up

# Follow container logs
1sec docker logs

# Show container status
1sec docker status

# Stop and remove containers
1sec docker down

# Build image from source
1sec docker build

# Pull latest image from registry
1sec docker pull

# Use a custom compose file or .env
1sec docker up --compose-file /path/to/docker-compose.yml

1sec init

Generate a starter configuration file with all modules and sane defaults.

# Generate full config
1sec init

# Generate minimal config
1sec init --minimal

# Generate config and prompt for Gemini API key
1sec init --ai

# Custom output path
1sec init --output /etc/1sec/config.yaml

# Overwrite existing file
1sec init --force

1sec logs

Fetch recent log entries from a running instance, with optional real-time tailing.

# Fetch last 50 log lines (default)
1sec logs

# Fetch more lines
1sec logs --lines 200

# Follow logs in real-time (like tail -f)
1sec logs --follow
1sec logs -f

# Custom poll interval for follow mode
1sec logs -f --poll-interval 1s

# Output as JSON, save to file
1sec logs --json --output logs.json

1sec events

Submit a SecurityEvent to the event bus via the API. Reads JSON from stdin or a file.

# Pipe event JSON from stdin
echo '{"type":"vulnerability_found","severity":"HIGH","summary":"CVE detected"}' | 1sec events

# Read from a file
1sec events --input event.json

# Output response as JSON
1sec events --input event.json --json

1sec export

Bulk export alerts or events in JSON, CSV, or SARIF format with filtering.

# Export all alerts as JSON (default)
1sec export

# Export as CSV
1sec export --format csv --output alerts.csv

# Export in SARIF format (for GitHub/GitLab integration)
1sec export --format sarif --output results.sarif

# Export only critical alerts from a specific module
1sec export --severity CRITICAL --module injection_shield

# Export events instead of alerts
1sec export --type events --output events.json

# Limit records
1sec export --limit 500

1sec profile

Manage named configuration profiles for switching between environments (dev, staging, prod).

# List all profiles
1sec profile list

# Create a new profile
1sec profile create staging

# Create from existing config
1sec profile create prod --from /etc/1sec/prod.yaml

# Create minimal profile
1sec profile create dev --minimal --description "Local dev"

# Show profile details
1sec profile show staging

# Set as default (via ONESEC_PROFILE env var)
1sec profile use prod

# Delete a profile
1sec profile delete old-config

# Use a profile with any command
1sec status --profile staging
1sec alerts --profile prod --severity CRITICAL

1sec dashboard

Launch a live TUI dashboard that polls the API and displays real-time module status, alerts, and activity.

# Launch dashboard (default 3s refresh)
1sec dashboard

# Custom refresh interval
1sec dashboard --refresh 1s

# Connect to remote instance
1sec dashboard --host 10.0.0.5 --port 1780

# Use a named profile
1sec dashboard --profile prod

1sec completions

Generate shell completion scripts for tab-completion of commands, flags, and module names.

# Bash — add to ~/.bashrc
source <(1sec completions bash)

# Zsh — add to ~/.zshrc
source <(1sec completions zsh)

# Fish
1sec completions fish | source

# PowerShell
1sec completions powershell | Out-String | Invoke-Expression

1sec help

Show help for any command.

1sec help
1sec help up
1sec help alerts
1sec help docker
1sec help export
1sec help profile

1sec correlator

Inspect the threat correlator state — active source windows, attack chain definitions, and cross-module correlation status.

# Show correlator status
1sec correlator

# Output as JSON
1sec correlator --json

# Use a named profile
1sec correlator --profile prod

1sec threats

Query dynamic IP threat scoring — shows tracked IPs, accumulated threat points, contributing modules, and block status.

# Show all tracked IPs
1sec threats

# Show only blocked IPs
1sec threats --blocked

# Output as JSON
1sec threats --json

# Output as CSV
1sec threats --format csv

# Save to file
1sec threats --format csv --output threats.csv

1sec rust

Check the Rust sidecar engine status — running state, worker count, pattern matching settings, and packet capture config.

# Show Rust engine status
1sec rust

# Output as JSON
1sec rust --json

1sec enforce

Manage the automated response / enforcement layer — status, policies, history, enable/disable, dry-run, test, presets, approvals, and webhooks.

# Show enforcement engine status
1sec enforce status

# List all response policies
1sec enforce policies

# Show action execution history
1sec enforce history
1sec enforce history --module ransomware --limit 20

# Enable/disable enforcement for a module
1sec enforce enable ransomware
1sec enforce disable auth_fortress

# Toggle global dry-run mode
1sec enforce dry-run on
1sec enforce dry-run off

# Simulate an alert and preview actions
1sec enforce test injection_shield --severity CRITICAL

# Apply a preset
1sec enforce preset balanced --show
1sec enforce preset strict --dry-run

# Webhook dispatcher management
1sec enforce webhooks stats
1sec enforce webhooks dead-letters
1sec enforce webhooks retry <id>

# Approval gate management
1sec enforce approvals pending
1sec enforce approvals approve <id>
1sec enforce approvals reject <id>
1sec enforce approvals history

# Output as JSON
1sec enforce status --format json
1sec enforce policies --format json

1sec collect

Start a reference collector that tails log files and publishes canonical schema events to the event bus. Connects to a running 1-SEC instance via NATS.

# Tail nginx access logs
1sec collect nginx --log-path /var/log/nginx/access.log

# Tail SSH/PAM auth logs
1sec collect auth --log-path /var/log/auth.log

# Tail pfSense/OPNsense filterlog
1sec collect pfsense --log-path /var/log/filterlog.log

# Tail JSON-line logs (CloudTrail, k8s audit)
1sec collect json --log-path /var/log/cloudtrail.json

# Poll GitHub Actions workflow runs
1sec collect github --log-path myorg/myrepo

# Custom source tag
1sec collect nginx --log-path /var/log/nginx/access.log --tag web-prod

# Connect to remote NATS
1sec collect auth --log-path /var/log/auth.log --nats-url nats://10.0.0.5:4222

1sec archive

Manage the cold archive — inspect status, list files, and restore archived events back into the engine.

# Show archiver metrics from running instance
1sec archive status

# List archive files on disk
1sec archive ls

# Restore events from a date range
1sec archive restore --from 2026-02-01 --to 2026-02-15

# Restore only specific event types
1sec archive restore --from 2026-02-20 --types auth_failure,login_failure

# Dry-run restore (count events without restoring)
1sec archive restore --from 2026-02-20 --dry-run

# Custom archive directory
1sec archive ls --dir /mnt/archive

1sec setup

Guided interactive setup wizard. Walks you through config creation, AI key setup (BYOK), and API security in one flow.

# Full interactive setup
1sec setup

# Only configure AI (Gemini) API keys
1sec setup --ai-only

# Non-interactive mode (uses env vars, no prompts)
GEMINI_API_KEY=xxx 1sec setup --non-interactive

# Use a specific config path
1sec setup --config /etc/1sec/config.yaml

1sec config set-key

Set Gemini API key(s) for AI-powered threat analysis. Supports multiple keys for automatic load balancing and rate-limit rotation.

# Set a single key
1sec config set-key AIzaSy...

# Set multiple keys (automatic rotation on rate limits)
1sec config set-key key1 key2 key3

# Import keys from GEMINI_API_KEY* environment variables
1sec config set-key --env

# Show current key status (masked)
1sec config set-key --show

# Get a free key
# https://aistudio.google.com/apikey

1sec doctor

Comprehensive health check with actionable fix suggestions. Goes beyond 'check' by detecting misconfigurations, checking AI readiness, and suggesting specific commands to fix issues.

# Run full diagnostics
1sec doctor

# Use a specific config
1sec doctor --config /etc/1sec/prod.yaml

# Use a named profile
1sec doctor --profile prod

# Example output:
#   ✓  [config]    Config loaded from configs/default.yaml
#   ✓  [ports]     API port 1780 available
#   !  [ai]        AI engine enabled but no API keys configured
#   !  [security]  REST API has no authentication
#
#   Suggested fixes:
#     ▸  1sec config set-key <your-gemini-key>
#     ▸  1sec setup --ai-only=false

API Endpoints

The REST API runs on port 1780 by default. All endpoints return JSON. CORS is restricted to configured origins (see cors_origins in config).

GET/healthHealth check endpoint.

GET/api/v1/statusEngine status, module list, bus connection, and alert count.

GET/api/v1/modulesList all registered modules with name, description, and enabled state.

GET/api/v1/alertsRecent alerts. Supports ?limit=N and ?min_severity=CRITICAL|HIGH|MEDIUM|LOW.

GET/api/v1/alerts/{id}Get a single alert by ID.

PATCH/api/v1/alerts/{id}Update alert status (OPEN, ACKNOWLEDGED, RESOLVED, FALSE_POSITIVE).

DELETE/api/v1/alerts/{id}Delete a single alert by ID.

POST/api/v1/alerts/clearClear all stored alerts.

GET/api/v1/configCurrent engine configuration.

POST/api/v1/eventsIngest an external SecurityEvent into the event bus.

GET/api/v1/logsRecent log entries. Supports ?limit=N.

GET/api/v1/correlatorThreat correlator state — active source windows, attack chain definitions, and correlation status.

GET/api/v1/threatsDynamic IP threat scores — tracked IPs, accumulated points, contributing modules, and block status.

GET/api/v1/rustRust sidecar engine status — running state, worker count, buffer size, Aho-Corasick settings, and packet capture config.

POST/api/v1/shutdownGracefully shut down the engine remotely.

Enforcement

GET/api/v1/enforce/statusEnforcement engine status, dry-run mode, and action statistics.

GET/api/v1/enforce/policiesAll configured response policies by module.

GET/api/v1/enforce/historyResponse action audit trail. Supports ?limit=N and ?module=name.

POST/api/v1/enforce/policies/{module}/{enable|disable}Enable or disable enforcement for a module at runtime.

POST/api/v1/enforce/dry-run/{on|off}Toggle global dry-run mode.

POST/api/v1/enforce/test/{module}Simulate an alert and preview matching actions. Supports ?severity=HIGH.

SOC Operations

GET/api/v1/enforce/webhooks/statsWebhook dispatcher stats — queue depth, dead letters, open circuits.

GET/api/v1/enforce/webhooks/dead-lettersFailed webhook deliveries. Supports ?limit=N.

POST/api/v1/enforce/webhooks/retry/{id}Re-enqueue a dead letter delivery for retry.

GET/api/v1/enforce/batching/statsAlert batcher state — active batches, window config.

GET/api/v1/enforce/escalations/statsEscalation manager state — tracked alerts, escalation counts.

GET/api/v1/enforce/approvals/pendingList all actions awaiting human approval.

POST/api/v1/enforce/approve/{id}Approve a pending destructive action.

POST/api/v1/enforce/reject/{id}Reject a pending destructive action.

GET/api/v1/enforce/approvals/historyApproval decision history. Supports ?limit=N.

GET/api/v1/enforce/chainsList all registered action chains.

GET/api/v1/enforce/chains/recordsChain execution audit trail. Supports ?limit=N.

Observability & Operations

GET/api/v1/metricsBus and routing metrics — events routed, events by type, module errors, routing skipped.

GET/api/v1/event-schemasCanonical event type spec with required Detail keys. Supports ?category= filter.

GET/api/v1/archive/statusCold archiver metrics — events/alerts archived, files rotated, bytes written, sampling stats.

POST/api/v1/config/reloadHot-reload configuration from disk. Returns list of changes applied.

Cloud Dashboard Ingest

POST/api/v1/ingestReceive enforcement records, correlation alerts, or instance heartbeats from local 1-SEC instances. Requires type field (enforcement | correlation | heartbeat).

GET/api/v1/ingestRetrieve stored enforcement, correlation, and instance data for the cloud dashboard. Supports ?type= filter.

Example: Fetch alerts

curl -s http://localhost:1780/api/v1/alerts?min_severity=CRITICAL&limit=10 | jq .

# Response:
# {
#   "alerts": [
#     {
#       "id": "a-29f1c...",
#       "module": "injection_shield",
#       "severity": "CRITICAL",
#       "title": "SQL injection detected in /api/users",
#       "status": "OPEN",
#       "timestamp": "2026-02-19T10:32:00Z"
#     }
#   ],
#   "total": 1
# }

Example: Ingest external event

curl -X POST http://localhost:1780/api/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "module": "external_scanner",
    "type": "vulnerability_found",
    "severity": "HIGH",
    "summary": "CVE-2026-1234 detected on host 10.0.0.5"
  }'

# Response:
# { "status": "accepted", "event_id": "ext-20260219103200.000" }

Configuration

1-SEC uses YAML configuration. Zero-config works out of the box with sane defaults. Place your config at configs/default.yaml or pass --config.

configs/default.yaml

server:
  host: "0.0.0.0"
  port: 1780
  # tls_cert: "/etc/1sec/tls/server.crt"
  # tls_key:  "/etc/1sec/tls/server.key"

bus:
  url: "nats://127.0.0.1:4222"
  embedded: true
  data_dir: "./data/nats"
  port: 4222
  cluster_id: "1sec-cluster"

alerts:
  max_store: 10000
  enable_console: true
  # webhook_urls:
  #   - "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

logging:
  level: "info"       # debug, info, warn, error
  format: "console"   # console, json

modules:
  network_guardian:
    enabled: true
    settings:
      max_requests_per_minute: 1000
      burst_size: 100
  injection_shield:
    enabled: true
  auth_fortress:
    enabled: true
    settings:
      max_failures_per_minute: 10
      lockout_duration_seconds: 300
      stuffing_threshold: 50
  ransomware:
    enabled: true
    settings:
      encryption_threshold: 10
      exfil_mb_threshold: 100
  llm_firewall:
    enabled: true
    settings:
      token_budget_per_hour: 100000
  runtime_watcher:
    enabled: true
    settings:
      scan_interval_seconds: 300
  ai_analysis_engine:
    enabled: true
    settings:
      triage_model: "gemini-flash-lite-latest"
      deep_model: "gemini-flash-latest"
      triage_workers: 4
      deep_workers: 2

# Enforcement — automated response to alerts
enforcement:
  enabled: true
  dry_run: true
  preset: "safe"    # lax, safe, balanced, strict, vps-agent

# Cold archive — indefinite event retention
archive:
  enabled: false
  dir: "./data/archive"
  rotate_bytes: 104857600     # 100MB
  rotate_interval: "1h"
  compress: true
  # sample_rules:
  #   - event_type: "dns_query"
  #     max_severity: "INFO"
  #     sample_rate: 100

# Optional Rust high-performance sidecar
rust_engine:
  enabled: false
  binary: "1sec-engine"
  capture:
    enabled: false
    interface: "eth0"

AI API keys are read from environment variables: GEMINI_API_KEY, GEMINI_API_KEY_2, GEMINI_API_KEY_3, etc. Multiple keys enable automatic rotation for rate limit management. You can also set them directly in the YAML under ai_analysis_engine.settings.gemini_api_key or gemini_api_keys (array).

Modules

[ Tier 1: Network & Perimeter ]

Network Guardian

network_guardian

DDoS mitigation, rate limiting, IP reputation, geo-fencing, DNS tunneling and DGA detection, C2 beaconing analysis, lateral movement monitoring (Pass-the-Hash, Kerberoasting, Golden Ticket, DCSync), port scan detection, amplification/reflection attack handling, and dynamic IP threat scoring (auto-blocks repeat offenders across modules at 50 points from 2+ modules).

API Fortress

api_fortress

BOLA detection, API schema validation against OpenAPI specs, shadow API discovery, per-endpoint rate limiting, security misconfiguration detection (API8:2023), and unsafe API consumption monitoring (API10:2023).

IoT & OT Shield

iot_shield

Device fingerprinting, protocol anomaly detection for MQTT/CoAP/Modbus/DNP3/BACnet/OPC-UA, firmware integrity verification, default credential detection (Dell RP4VM, HPE iLO, Lenovo XClarity, Supermicro IPMI), OT command validation, persistent firmware implant detection (HiatusRAT-X), ICS wiper malware detection (VoltRuptor), and coordinated multi-protocol OT attack detection (SYLVANITE/PYROXENE/AZURITE patterns).

[ Tier 2: Application Layer ]

Injection Shield

injection_shield

Detects and blocks SQLi (including blind boolean/time/error-based), XSS, SSRF, command injection, template injection, NoSQL injection, path traversal, Zip Slip archive traversal, deserialization RCE (Java/PHP/.NET/Python pickle), and canary token detection (AWS keys, GitHub tokens, Slack tokens, private keys, JWTs, GCP service accounts). All inputs pass through an 8-phase normalization pipeline (hex decoding, HTML entities, backslash escapes, null byte stripping, SQL comment removal, Unicode whitespace, homoglyph mapping, space collapsing).

Supply Chain Sentinel

supply_chain

SBOM generation, package integrity verification, CI/CD pipeline hardening, typosquatting detection, and dependency confusion prevention.

Ransomware Interceptor

ransomware

Encryption pattern detection (threshold: 5 files), canary files, exfiltration monitoring, wiper detection (MBR/GPT overwrite, zero-fill, partition destruction), shadow copy deletion, backup destruction, service stop detection, compound attack correlation with MITRE ATT&CK mapping, intermittent/partial encryption detection, ESXi/hypervisor ransomware targeting (Akira, BlackCat), SSH tunneling for lateral movement, pre-ransomware credential harvesting (Mimikatz, LSASS, NTLM, Kerberos), and Linux ransomware patterns.

[ Tier 3: Identity & Access ]

Auth Fortress

auth_fortress

Brute force protection, credential stuffing, session hijack, impossible travel, MFA bypass and fatigue detection, OAuth token abuse, consent phishing, password spray detection, stolen token tracking, AitM/adversary-in-the-middle detection, passkey/FIDO2/WebAuthn monitoring, and auth downgrade detection.

Deepfake Shield

deepfake_shield

Synthetic voice and video detection, AI-generated phishing content identification, domain spoofing, and BEC detection.

Identity Fabric Monitor

identity_monitor

Synthetic identity detection, privilege escalation monitoring, and service account anomaly tracking.

[ Tier 4: AI-Specific Defense ]

LLM Firewall

llm_firewall

65+ prompt injection patterns, jailbreak detection, output filtering, multi-turn attack tracking, encoding evasion detection, tool-chain abuse monitoring, token budget enforcement, excessive agency monitoring (LLM06), system prompt leakage detection (LLM07), RAG/embedding weakness analysis (LLM08), misinformation detection (LLM09), and multimodal hidden injection scanning (image metadata, HTML/CSS, PDF hidden text). Zero LLM calls, zero OCR, zero external dependencies.

AI Agent Containment

ai_containment

Action sandboxing for autonomous agents, tool-use monitoring, shadow AI detection, policy enforcement, OWASP Agentic AI Top 10 coverage, tool integrity monitoring, goal hijack detection, memory poisoning detection, and cascade failure monitoring.

Data Poisoning Guard

data_poisoning

Training data integrity verification, RAG pipeline validation, adversarial input detection, model drift monitoring, and model supply chain attack detection (slopsquatting, unsigned models).

[ Tier 5: Cryptography ]

Quantum-Ready Crypto

quantum_crypto

Cryptographic inventory scanning, post-quantum migration readiness, TLS auditing, certificate monitoring, crypto-agility enforcement, and harvest-now-decrypt-later (HNDL) pattern detection for bulk encrypted traffic capture targeting quantum-vulnerable ciphers.

[ Tier 6: Runtime & Infrastructure ]

Runtime Watcher

runtime_watcher

File integrity monitoring, container escape detection, privilege escalation, LOLBin detection (40+ Living Off the Land Binaries with MITRE ATT&CK IDs), memory injection detection (process hollowing, DLL injection, reflective loading), persistence mechanism detection (scheduled tasks, WMI, registry, cron, systemd), firmware/UEFI tampering, fileless malware detection, symlink/link-following privilege escalation, ETW bypass and logging evasion detection, and Lua-based shellcode loader detection.

Cloud Posture Manager

cloud_posture

Configuration drift detection, misconfiguration scanning, secrets sprawl prevention, compliance checks, Kubernetes RBAC auditing, container posture checks, and KSPM.

[ Cross-Cutting ]

AI Analysis Engine

ai_analysis_engine

Two-tier LLM pipeline: Gemini Flash Lite for high-volume triage and false positive discard, Gemini Flash for deep threat classification and cross-module correlation. Supports multi-key rotation for rate limit management.

[ Core ]

Threat Correlator

threat_correlator

Cross-module attack chain detection — automatically correlates alerts from multiple modules targeting the same source IP within a 15-minute window into unified incident alerts. 9 pre-defined attack chains covering kill chain, credential→lateral, injection→persistence, ransomware, supply chain, API abuse, AI attacks, cloud compromise, and IoT pivot patterns.

Reference Collectors

Built-in log tailers that run inside the 1-SEC binary — no external agents needed. Collectors tail log files and emit canonical schema events to the NATS bus, immediately unlocking detection across all 16 modules.

Supported Collectors

nginx

Tails nginx/apache combined access logs. Emits http_request events with method, path, status, user agent, and response size.

authlog

Tails /var/log/auth.log. Emits auth_failure, auth_success, and session_activity events.

pfsense

Tails pfSense/OPNsense filterlog. Emits network_connection events with protocol, ports, and action.

jsonlog

Tails JSON-line logs (CloudTrail, k8s audit). Auto-classifies events based on content fields.

github

Polls GitHub Actions API for workflow runs. Emits cicd_event events. Flags failures and suspicious triggers.

syslog

Built-in syslog listener (UDP/TCP). Enriches raw syslog with source classification and severity mapping.

Collectors set event.Source = "collector:<name>" so you can distinguish collector-generated events from module-generated events in alerts and the archive.

Safety constraints: collectors require explicit file paths (no arbitrary file reads), enforce max line sizes, and never execute commands.

Cold Archive

Indefinite event retention without a SIEM. The archiver subscribes to all events, alerts, and responses with a separate durable JetStream consumer and writes compressed NDJSON files to disk. JetStream remains the "hot buffer" (7-30 days); the archive is forever.

How It Works

Write

NDJSON format (one JSON record per line) with gzip compression. Each record wraps the original event/alert data.

Rotate

Files rotate by size (default 100MB) or time (default 1 hour), whichever comes first.

Sample

Optional sampling rules drop low-severity high-volume events (e.g., keep 1% of INFO dns_query). Alerts are never sampled.

Restore

Replay archived events back into the engine by date range and event type via 1sec archive restore.

Archive Config

archive:
  enabled: true
  dir: "./data/archive"
  rotate_bytes: 104857600     # 100MB
  rotate_interval: "1h"
  compress: true
  sample_rules:
    - event_type: "dns_query"
      max_severity: "INFO"
      sample_rate: 100        # keep 1% of INFO dns_query events
    - event_type: "http_request"
      max_severity: "LOW"
      sample_rate: 10         # keep 10% of LOW http_request events

Restore from Archive

# Restore all events from a date range
1sec archive restore --from 2026-02-01 --to 2026-02-15

# Restore only auth events (dry-run first)
1sec archive restore --from 2026-02-20 --types auth_failure,login_failure --dry-run

# Check archive status
1sec archive status

# List archive files
1sec archive ls

Canonical Event Schema

130+ canonical event types organized into categories. Every event type defines required Detail keys so collectors, modules, and external integrations produce consistent data. The schema is queryable via GET /api/v1/event-schemas.

Event Schema API

# List all event schemas
curl -s http://localhost:1780/api/v1/event-schemas | jq .

# Filter by category
curl -s http://localhost:1780/api/v1/event-schemas?category=auth | jq .

# Categories: network, auth, injection, runtime, supply_chain,
#   ransomware, ai, identity, iot, crypto, cloud, cicd, api, deepfake

SecurityEvent Structure

{
  "id": "evt-20260220T100000Z-abc123",
  "module": "collector:nginx",
  "type": "http_request",           // canonical event type
  "severity": "INFO",               // INFO, LOW, MEDIUM, HIGH, CRITICAL
  "summary": "GET /api/users 200",
  "source_ip": "10.0.0.5",
  "timestamp": "2026-02-20T10:00:00Z",
  "details": {                      // type-specific required keys
    "method": "GET",
    "path": "/api/users",
    "status_code": "200",
    "user_agent": "Mozilla/5.0..."
  },
  "raw_data": "10.0.0.5 - - [20/Feb/2026:10:00:00 +0000] ..."
}

Event Deduplication

SHA256-based dedup cache prevents the same event from being processed twice — for example when the syslog listener and a collector both ingest the same log line. Events are fingerprinted by type + source_ip + summary + raw_data prefix with a 30-second TTL and 50K max entries.

Dedup runs automatically in the event routing pipeline. No configuration needed. Duplicate events are logged at debug level and never reach modules.

Config Hot-Reload

Reload configuration without restarting the engine. Edit the YAML file and POST to the reload endpoint.

Hot-Reload via API

curl -X POST http://localhost:1780/api/v1/config/reload \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "status": "reloaded",
#   "changes": [
#     "logging.level → debug",
#     "enforcement.dry_run → false",
#     "enforcement.preset → balanced",
#     "module iot_shield disabled"
#   ]
# }

Hot-reloadable settings:

Enforcement policies, preset, dry_run, global_allow_list
Alert webhook URLs
Module enable/disable
Logging level
API keys and CORS origins
Archive sampling rules

NOT hot-reloadable (require restart): bus config, server host/port, TLS config.

Architecture

All 16 modules communicate through an embedded NATS JetStream event bus with filtered event routing — each module only receives events it declared interest in via EventTypes(). Reference collectors publish canonical events to the bus. An SHA256 dedup cache prevents duplicate processing. Alerts flow through an AlertPipeline with configurable handlers. The Threat Correlator detects multi-stage attack chains. The cold archiver subscribes with a separate durable consumer for indefinite retention. Panic recovery wraps every module dispatch so a crashing module cannot take down the engine.

Architecture Overview

1-SEC CLI / API

REST :1780 · Syslog :1514

NATS JetStream Event Bus

sec.events.> · sec.alerts.> · sec.matches.> · sec.responses.>

NetAPIIoTInjSCRanAuthDFIDLLMAICDPQCRTCPAI

16 modules

Threat Correlator

Cross-module attack chain detection

Response Engine

Enforcement · Block · Kill · Quarantine

Collectors

nginx · authlog · pfSense · JSON · GitHub

Cold Archiver

NDJSON+gzip · Sampling · Restore

Rust Engine

Pattern matching · Packet capture · PQC

AI Analysis

Gemini triage · Deep analysis

Module Interface (Go)

type Module interface {
    Name() string
    Description() string
    Start(ctx context.Context, bus *EventBus, pipeline *AlertPipeline, cfg *Config) error
    Stop() error
    HandleEvent(event *SecurityEvent) error
    EventTypes() []string  // filtered routing — return nil for all events
}

The AI Analysis Engine operates as a cross-cutting concern with two tiers:

Tier 1 (Triage): Gemini Flash Lite — high-volume event pre-filtering and false positive discard
Tier 2 (Deep Analysis): Gemini Flash — threat classification and cross-module correlation

Event bus streams:

sec.events.> — SecurityEvent stream (7-day retention, 1GB max)
sec.alerts.> — Alert stream (30-day retention, 512MB max)
sec.matches.> — Rust engine pattern match results (7-day retention, 512MB max)
sec.responses.> — Enforcement action audit records (7-day retention, 256MB max)

Rust Engine

The optional Rust sidecar provides high-performance pattern matching, raw packet capture, and post-quantum cryptographic operations. It connects to the same NATS JetStream bus as the Go engine and processes events in parallel. The Go engine works perfectly without it — the Rust engine is an optimization layer for high-throughput deployments.

What it provides

Regex Engine

63 attack patterns across 15 categories with Aho-Corasick pre-filtering. 5-10x faster than Go's RE2 for hot-path matching across SQLi (including blind), XSS, CMDi, SSRF, LDAP injection, template injection, NoSQL injection, path traversal, prompt injection, ransomware, auth bypass, exfiltration, deserialization RCE, canary tokens, and Zip Slip.

Packet Capture

Raw pcap capture with zero-copy protocol parsing via etherparse. Port scan detection, Christmas tree / NULL scan detection, payload text extraction, and anomaly tracking.

PQC Crypto

Post-quantum cryptographic operations (ML-KEM, ML-DSA) when compiled with the pqc feature flag.

Build from source

cd rust/1sec-engine

# Build with packet capture (requires libpcap-dev)
cargo build --release

# Build without pcap (no system dependencies)
cargo build --release --no-default-features

# Build with all features including PQC
cargo build --release --all-features

# Or use the build script
./build.sh              # Default (with pcap)
./build.sh --no-pcap    # Without pcap
./build.sh --all        # All features

Enable in config

# configs/default.yaml
rust_engine:
  enabled: true
  binary: "1sec-engine"    # Path to binary (searches PATH)
  workers: 0               # 0 = auto-detect CPU cores
  buffer_size: 10000
  min_score: 0.0
  aho_corasick_prefilter: true
  capture:
    enabled: false         # Requires root or CAP_NET_RAW
    interface: "eth0"
    promiscuous: true

Run standalone

# The Rust engine can also run independently
1sec-engine --nats-url nats://127.0.0.1:4222

# With packet capture
1sec-engine --nats-url nats://127.0.0.1:4222 --capture --interface eth0

# With custom config and log options
1sec-engine --config /path/to/config.yaml --log-level debug --log-format json

NATS streams used by the Rust engine:

sec.events.> — Subscribes as durable consumer rust-engine
sec.matches.> — Publishes pattern match results
sec.events.packet_capture.> — Publishes parsed packet events

When enabled via rust_engine.enabled: true, the Go engine auto-starts the Rust binary as a supervised subprocess with exponential backoff restart (up to 10 retries). The /api/v1/status endpoint reports the Rust engine status.

Deployment

Single Binary

# Download and run
curl -fsSL https://1-sec.dev/get | sh
1sec up

Docker Compose

# From the repo root — uses deploy/docker/docker-compose.yml
cd deploy/docker
echo "GEMINI_API_KEY=your_key" > .env
docker compose up -d
docker compose logs -f

# Or use the CLI shortcut from anywhere in the repo:
1sec docker up
1sec docker logs
1sec docker status
1sec docker down

Environment Variables

GEMINI_API_KEY        # Primary Gemini API key for AI Analysis Engine
GEMINI_API_KEY_2      # Additional keys for rotation (rate limit management)
GEMINI_API_KEY_3      # ...
ONESEC_API_KEY        # Secure the REST API (optional)
ONESEC_CLOUD_API_KEY  # Pro/Enterprise cloud dashboard key

Kubernetes

The Helm chart at deploy/helm/ deploys 1-SEC to any Kubernetes cluster. It includes a PVC for NATS JetStream persistence, health probes, a non-root security context, and optional Ingress.

Install

# Install with defaults
helm install 1sec ./deploy/helm

# Install with Gemini AI key
helm install 1sec ./deploy/helm \
  --set env.GEMINI_API_KEY=your_key_here

# Install with custom config
helm install 1sec ./deploy/helm \
  --set env.GEMINI_API_KEY=your_key_here \
  --set-string config="$(cat my-config.yaml)"

# Upgrade
helm upgrade 1sec ./deploy/helm --reuse-values

Operations

# Check engine status
kubectl exec deploy/1sec -- 1sec status

# Run pre-flight diagnostics
kubectl exec deploy/1sec -- 1sec check

# Fetch recent critical alerts
kubectl exec deploy/1sec -- 1sec alerts --severity CRITICAL --json

# Follow logs
kubectl logs -l app.kubernetes.io/name=1sec -f

# Port-forward the REST API locally
kubectl port-forward svc/1sec 1780:1780

values.yaml — key overrides

# Use an existing Kubernetes Secret instead of inline env vars
existingSecret: "my-1sec-secrets"

# Increase resource limits for high-traffic environments
resources:
  limits:
    cpu: "4"
    memory: 1Gi

# Enable Ingress for the REST API
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: 1sec.example.com
      paths:
        - path: /api
          pathType: Prefix
  tls:
    - secretName: 1sec-tls
      hosts:
        - 1sec.example.com

# Expand NATS storage
persistence:
  size: 20Gi

Shell Completions

1-SEC provides tab-completion for all commands, subcommands, flags, module names, and severity levels. Supported shells: Bash, Zsh, Fish, and PowerShell.

Bash

# Add to ~/.bashrc for persistent completions
echo 'source <(1sec completions bash)' >> ~/.bashrc
source ~/.bashrc

Zsh

# Add to ~/.zshrc
echo 'source <(1sec completions zsh)' >> ~/.zshrc
source ~/.zshrc

Fish

# Add to Fish config
1sec completions fish > ~/.config/fish/completions/1sec.fish

PowerShell

# Add to your PowerShell profile
1sec completions powershell >> $PROFILE

Completions cover:

All 21 top-level commands (up, stop, status, alerts, scan, modules, config, check, logs, events, export, profile, dashboard, init, docker, completions, enforce, collect, archive, version, help)
Subcommands for alerts (ack, resolve, false-positive, get, delete, clear), modules (info, enable, disable), docker (up, down, logs, status, build, pull), profile (list, create, show, delete, use), enforce (status, policies, history, enable, disable, dry-run, test, preset, webhooks, approvals, batching, escalations, chains), archive (status, ls, restore)
All 16 module names for --module and modules info/enable/disable
Severity levels (INFO, LOW, MEDIUM, HIGH, CRITICAL) and output formats (table, json, csv, sarif)
File path completion for --config, --output, and --input flags

Threat Correlator

The Threat Correlator is a core engine component that watches the alert pipeline and automatically detects multi-stage attack chains. When multiple modules fire alerts for the same source IP within a 15-minute window, the correlator matches them against 9 pre-defined attack chain patterns and emits a unified CRITICAL incident alert.

Attack Chain Patterns

Kill Chain

network → injection → runtime (full intrusion lifecycle)

Credential → Lateral

auth → network (stolen creds used for lateral movement)

Injection → Persistence

injection → runtime (exploit followed by persistence install)

Ransomware Chain

injection → ransomware (exploit leading to encryption)

Supply Chain Attack

supply_chain → runtime (compromised package executing)

API Abuse Chain

api_fortress → injection (API probing into exploitation)

AI Attack Chain

llm_firewall → data_poisoning (prompt injection into data poisoning)

Cloud Compromise

cloud_posture → identity (misconfig exploited for privilege escalation)

IoT Pivot

iot → network (compromised device used as network pivot)

The correlator runs automatically as part of the engine — no configuration needed. Correlated alerts include all contributing module alerts in their metadata, making it easy to trace the full attack timeline. Alerts carry source_ip metadata for cross-module correlation.

Enforcement

The enforcement layer is a SOAR-lite automated response engine that subscribes to alerts and executes configurable response actions. It covers all 16 modules with per-module policies, severity thresholds, cooldowns, rate limits, allow lists, and dry-run mode. Start in dry-run to audit what would happen, then go live when ready.

How It Works

1. A module raises an alert (e.g., injection_shield detects SQLi)

2. The Response Engine checks the module's policy — is enforcement enabled? Does severity meet the threshold?

3. Allow lists, cooldowns, and rate limits are checked

4. If dry-run is active, the action is logged but not executed

5. Otherwise, the action fires (block IP, kill process, webhook, etc.)

6. Every decision is recorded in the audit trail and published to NATS

Action Types

block_ip

Add IP to system firewall deny rules with auto-unblock after a configurable duration.

kill_process

Terminate a malicious process by PID or name.

quarantine_file

Move suspicious file to quarantine directory.

drop_connection

Reset/drop active network connections from source.

disable_user

Disable a user account (OS-level or custom command).

webhook

POST alert + action context to a URL (SIEM, Slack, PagerDuty).

command

Run an arbitrary shell command with alert template variables.

log_only

Record the alert without taking enforcement action.

Presets

Presets provide a starting point for all 16 modules. They are a base layer — you can override any module's policy in your YAML config, or skip presets entirely for 100% custom configuration.

lax

Pure observe mode. Log and webhook only. Never blocks, kills, or quarantines. For initial rollout when you just want visibility.

safe (default)

Log + webhook for most modules. Blocks IPs only for confirmed brute force and port scans at CRITICAL. Kills processes only for confirmed ransomware at CRITICAL. Ultra conservative.

balanced

Blocks IPs on HIGH, kills processes on CRITICAL. Reasonable cooldowns (60s–300s). Good for production once you've audited with safe.

strict

Aggressive enforcement on MEDIUM+. Short cooldowns (10s–60s), high rate limits. Blocks, kills, quarantines, and drops connections. For high-security environments.

vps-agent

Purpose-built for VPS-hosted AI agents (OpenClaw, Moltbot, Manus). Aggressive on auth, LLM firewall, AI containment, runtime integrity, and supply chain. Relaxed on IoT, deepfake, and quantum. Not part of the escalation ladder — a standalone profile for the AI agent threat model.

Recommended progression: lax → safe → balanced → strict. The vps-agent preset is a standalone profile for AI agent VPS deployments. Start with safe + dry_run (the default), audit what fires, tune allow lists, then move up.

1sec enforce status

Show enforcement engine status — active/disabled, dry-run mode, policy count, action breakdown.

1sec enforce status

# Output:
# Enforcement Engine Status
#
#   Status:    ACTIVE
#   Mode:      DRY RUN (actions are simulated, not executed)
#   Preset:    safe
#   Policies:  18
#   Actions:   142
#   Breakdown: DRY_RUN=130, SUCCESS=8, COOLDOWN=4

# Output as JSON
1sec enforce status --format json

1sec enforce policies

List all configured response policies with severity thresholds, action counts, cooldowns, and rate limits.

1sec enforce policies

# Output:
# MODULE              ENABLED  DRY RUN  MIN SEVERITY  ACTIONS  COOLDOWN  RATE LIMIT
# network_guardian    ✓        no       HIGH          2        300s      20/min
# injection_shield    ✓        no       HIGH          2        60s       50/min
# ransomware          ✓        no       HIGH          3        60s       10/min
# ...

# Output as JSON
1sec enforce policies --format json

1sec enforce history

Show response action execution history with timestamps, targets, status, and duration.

# Show last 50 actions (default)
1sec enforce history

# Filter by module
1sec enforce history --module ransomware

# Limit results
1sec enforce history --limit 20

# Output as JSON
1sec enforce history --format json

1sec enforce enable / disable

Enable or disable enforcement for a specific module at runtime.

# Enable enforcement for ransomware module
1sec enforce enable ransomware

# Disable enforcement for auth_fortress
1sec enforce disable auth_fortress

1sec enforce dry-run

Toggle global dry-run mode. When on, all actions are logged but not executed.

# Enable dry-run (safe mode)
1sec enforce dry-run on

# Go live — actions will be executed
1sec enforce dry-run off

1sec enforce test

Simulate an alert for a module and preview what enforcement actions would fire.

# Test what happens on a HIGH alert from injection_shield
1sec enforce test injection_shield

# Test with CRITICAL severity
1sec enforce test ransomware --severity CRITICAL

# Output as JSON
1sec enforce test network_guardian --format json

1sec enforce preset

Apply an enforcement preset (lax, safe, balanced, strict) or preview its policies.

# See available presets
1sec enforce preset

# Preview what balanced does without applying
1sec enforce preset balanced --show

# Apply strict preset with dry-run enabled
1sec enforce preset strict --dry-run

# Apply lax preset (goes live immediately)
1sec enforce preset lax

# Output preset details as JSON
1sec enforce preset balanced --show --format json

Enforcement Config (YAML)

# configs/default.yaml
enforcement:
  enabled: true
  dry_run: true                # Start in dry-run to audit before going live
  preset: "balanced"           # lax | safe | balanced | strict
  global_allow_list:           # IPs never blocked (monitoring, VPN, LBs)
    - "10.0.0.1"
    - "192.168.1.0/24"

  # Override individual module policies (merges on top of preset):
  policies:
    network_guardian:
      enabled: true
      min_severity: "HIGH"
      cooldown_seconds: 300
      max_actions_per_min: 20
      allow_list: ["10.0.0.1"]
      actions:
        - action: block_ip
          min_severity: "HIGH"
          description: "Block source IP via system firewall"
          params:
            duration: "1h"
        - action: webhook
          min_severity: "CRITICAL"
          description: "Notify SOC team"
          params:
            url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
        - action: command
          min_severity: "CRITICAL"
          description: "Run custom remediation script"
          params:
            command: "/opt/1sec/scripts/block-ip.sh {{source_ip}}"
            timeout: "30s"

  # Template variables for 'command' action:
  #   {{alert_id}}, {{module}}, {{severity}}, {{source_ip}}, {{title}}

Enforcement API endpoints:

GET/api/v1/enforce/statusEnforcement engine status, dry-run mode, and action statistics.

GET/api/v1/enforce/policiesAll configured response policies by module.

GET/api/v1/enforce/historyResponse action audit trail. Supports ?limit=N and ?module=name.

POST/api/v1/enforce/policies/{module}/{enable|disable}Enable or disable enforcement for a module at runtime.

POST/api/v1/enforce/dry-run/{on|off}Toggle global dry-run mode.

POST/api/v1/enforce/test/{module}Simulate an alert and preview matching actions. Supports ?severity=HIGH.

GET/api/v1/enforce/approvals/pendingList actions awaiting human approval.

GET/api/v1/enforce/approvals/historyApproval decision history.

GET/api/v1/enforce/approvals/statsApproval gate statistics.

GET/api/v1/enforce/webhooks/statsWebhook dispatcher stats — queue depth, dead letters, open circuits.

GET/api/v1/enforce/webhooks/dead-lettersFailed webhook deliveries.

POST/api/v1/enforce/webhooks/retry/{id}Re-enqueue a dead letter delivery for retry.

Response records are published to the NATS stream:

sec.responses.> — Response action audit records (7-day retention)

Webhook Delivery

Reliable webhook delivery with exponential backoff, dead letter buffer, and circuit breaker. SOC teams depend on notifications reaching PagerDuty, Slack, and other tools — a transient 503 shouldn't silently drop a CRITICAL alert.

How It Works

Async Queue

Configurable queue (default 1000) with 4 background workers. Enqueue returns immediately.

Exponential Backoff

1s → 2s → 4s → 8s → 16s. Up to 5 retries. Retries on 5xx and 429, dead-letters on 4xx.

Dead Letters

Permanently failed deliveries stored for inspection and manual retry via API. Buffer holds up to 500 entries.

Circuit Breaker

If a URL fails 5 times consecutively, pause delivery for 60s. Prevents hammering a down endpoint.

Webhook Delivery Config

# configs/default.yaml
enforcement:
  webhook_delivery:
    max_retries: 5              # attempts before dead-lettering
    initial_backoff: "1s"       # first retry delay
    max_backoff: "30s"          # backoff cap
    queue_size: 1000            # async delivery queue depth
    workers: 4                  # concurrent delivery goroutines
    circuit_breaker_threshold: 5  # consecutive failures to trip
    circuit_pause: "60s"        # pause duration when circuit opens

Dead Letter API

# List failed deliveries
curl -s http://localhost:1780/api/v1/enforce/webhooks/dead-letters?limit=10 | jq .

# Retry a specific dead letter
curl -X POST http://localhost:1780/api/v1/enforce/webhooks/retry/DL_ID

# Check dispatcher stats
curl -s http://localhost:1780/api/v1/enforce/webhooks/stats | jq .
# {
#   "queue_depth": 0,
#   "queue_capacity": 1000,
#   "dead_letters": 3,
#   "open_circuits": 0,
#   "workers": 4,
#   "max_retries": 5
# }

Each delivery includes tracking headers:

X-1SEC-Delivery-ID — unique delivery identifier
X-1SEC-Attempt — current attempt number
User-Agent: 1sec-webhook-dispatcher/1.0

Notification Templates

Pre-built webhook payload formatters for PagerDuty, Slack, Microsoft Teams, Discord, and generic JSON. Each template produces the exact JSON schema the target service expects — no translation proxy needed.

Supported Templates

pagerduty

Events API v2 format with severity mapping, dedup keys, and custom details.

slack

Block Kit with header, fields, severity emoji, and color-coded attachments.

teams

MessageCard with theme colors, facts table, and markdown support.

discord

Rich embed with color-coded severity, inline fields, and timestamps.

generic

Raw alert JSON with action context. Default when no template specified.

Template Usage in Config

# configs/default.yaml
enforcement:
  policies:
    injection_shield:
      actions:
        # PagerDuty — triggers an incident
        - action: webhook
          min_severity: "CRITICAL"
          params:
            url: "https://events.pagerduty.com/v2/enqueue"
            template: "pagerduty"
            routing_key: "YOUR_PD_ROUTING_KEY"

        # Slack — posts to a channel
        - action: webhook
          min_severity: "HIGH"
          params:
            url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
            template: "slack"

        # Microsoft Teams
        - action: webhook
          min_severity: "HIGH"
          params:
            url: "https://outlook.office.com/webhook/YOUR/TEAMS/URL"
            template: "teams"

        # Discord
        - action: webhook
          min_severity: "MEDIUM"
          params:
            url: "https://discord.com/api/webhooks/YOUR/DISCORD/URL"
            template: "discord"

Severity mapping for PagerDuty:

CRITICAL → critical
HIGH → error
MEDIUM → warning
LOW/INFO → info

Template aliases: pd → pagerduty, msteams → teams.

Alert Batching

Batches and deduplicates notifications to prevent alert storms from flooding SOC channels. If injection_shield fires 50 alerts from the same IP in 10 seconds, the SOC gets one summary notification instead of 50 webhook calls.

How It Works

1. Alerts are grouped by module + source_ip into batches

2. A configurable time window (default 30s) collects alerts into each batch

3. When the window expires or the batch hits max size (default 50), a single BatchedNotification is emitted

4. The notification includes alert count, highest severity, severity breakdown, and sample alert IDs

Alert Batching Config

# configs/default.yaml
enforcement:
  alert_batching:
    enabled: true
    window_duration: "30s"    # group alerts within this window
    max_batch_size: 50        # flush immediately if batch hits this size

Batched Notification (JSON)

{
  "batch_id": "batch-injection_shield:10.0.0.5-1708425600000",
  "module": "injection_shield",
  "source_ip": "10.0.0.5",
  "alert_count": 23,
  "highest_severity": "CRITICAL",
  "first_seen": "2026-02-20T10:00:00Z",
  "last_seen": "2026-02-20T10:00:28Z",
  "sample_alert_ids": ["a-29f1c...", "a-38d2e...", "a-47b3f...", "a-56c4g...", "a-65d5h..."],
  "severity_counts": {
    "CRITICAL": 3,
    "HIGH": 12,
    "MEDIUM": 8
  }
}

Escalation Timers

Automatic escalation for unacknowledged alerts. If a CRITICAL alert sits unacknowledged for 5 minutes, the severity bumps, a new escalation alert fires through the pipeline, and the on-call gets paged again.

Behavior

Track

New alerts are automatically tracked with a per-severity timeout timer.

Escalate

On timeout: severity bumps, escalation alert fires, handlers notified. Repeats up to max_escalations.

Cancel

Acknowledging an alert cancels its escalation timer immediately.

Escalation Config

# configs/default.yaml
enforcement:
  escalation:
    enabled: true
    timeouts:
      CRITICAL:
        timeout: "5m"           # escalate after 5 minutes unacknowledged
        escalate_to: "CRITICAL" # stays CRITICAL but re-notifies
        re_notify: true         # fire a new alert through the pipeline
        max_escalations: 3      # stop after 3 escalation cycles
      HIGH:
        timeout: "15m"
        escalate_to: "CRITICAL" # bump HIGH → CRITICAL
        re_notify: true
        max_escalations: 2
      MEDIUM:
        timeout: "30m"
        escalate_to: "HIGH"     # bump MEDIUM → HIGH
        re_notify: true
        max_escalations: 1

Escalation alerts carry the prefix [ESCALATION #N] in their title and include the original alert metadata, making it easy to trace the escalation chain.

Approval Gates

Human-in-the-loop approval for destructive response actions. Actions like kill_process, quarantine_file, and disable_user are held pending until a human approves or rejects them via the API.

How It Works

1. Enforcement engine matches an alert to a destructive action (e.g., kill_process)

2. Approval gate intercepts — action is held in pending state

3. SOC analyst reviews via API or dashboard and approves/rejects

4. Approved actions execute immediately; rejected actions are logged

5. Unreviewed actions auto-expire after TTL (default 30 minutes)

Approval Gate Config

# configs/default.yaml
enforcement:
  approval_gate:
    enabled: true
    require_approval:           # action types that need human sign-off
      - "kill_process"
      - "quarantine_file"
      - "disable_user"
    ttl: "30m"                  # auto-expire pending actions after this
    max_pending: 100            # max concurrent pending approvals

Approval API

# List pending approvals
curl -s http://localhost:1780/api/v1/enforce/approvals/pending | jq .

# Approve an action
curl -X POST http://localhost:1780/api/v1/enforce/approve/APPROVAL_ID

# Reject an action
curl -X POST http://localhost:1780/api/v1/enforce/reject/APPROVAL_ID

# View approval history
curl -s http://localhost:1780/api/v1/enforce/approvals/history?limit=20 | jq .

Pending approval statuses:

pending — awaiting human decision
approved — action executed
rejected — action blocked by analyst
expired — TTL elapsed without decision

Action Chains

Conditional action chaining — basic playbook logic without an external orchestrator. Define "if action A succeeds, do B; if it fails, do C" sequences that execute automatically against alerts.

Chain Execution

Steps

Each step runs an action type (block_ip, webhook, command, etc.) with its own params, timeout, and retry count.

Branching

on_success and on_failure point to the next step name. Empty means stop.

Audit Trail

Every chain execution is recorded with per-step status, duration, and error details.

Action Chain Config (Playbook)

# configs/default.yaml
enforcement:
  action_chains:
    - name: "ransomware_response"
      description: "Full ransomware containment playbook"
      entry_point: "block_source"
      steps:
        - name: "block_source"
          action: "block_ip"
          params:
            duration: "24h"
          on_success: "kill_malware"
          on_failure: "notify_soc"

        - name: "kill_malware"
          action: "kill_process"
          max_retries: 2
          timeout: "10s"
          on_success: "quarantine_files"
          on_failure: "notify_soc"

        - name: "quarantine_files"
          action: "quarantine_file"
          on_success: "notify_soc"
          on_failure: "notify_soc"

        - name: "notify_soc"
          action: "webhook"
          params:
            url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
            template: "slack"

    - name: "credential_theft_response"
      description: "Lock account and notify on credential theft"
      entry_point: "disable_account"
      steps:
        - name: "disable_account"
          action: "disable_user"
          on_success: "block_and_notify"
          on_failure: "emergency_notify"

        - name: "block_and_notify"
          action: "block_ip"
          params:
            duration: "1h"
          on_success: "page_soc"

        - name: "page_soc"
          action: "webhook"
          params:
            url: "https://events.pagerduty.com/v2/enqueue"
            template: "pagerduty"
            routing_key: "YOUR_PD_KEY"

        - name: "emergency_notify"
          action: "webhook"
          params:
            url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
            template: "slack"

Chain Execution Record (JSON)

{
  "id": "exec-abc123",
  "chain_name": "ransomware_response",
  "alert_id": "a-29f1c...",
  "started_at": "2026-02-20T10:00:00Z",
  "finished_at": "2026-02-20T10:00:12Z",
  "status": "completed",
  "steps": [
    {
      "step_name": "block_source",
      "action": "block_ip",
      "status": "success",
      "target": "10.0.0.5",
      "duration_ms": 45,
      "next_step": "kill_malware"
    },
    {
      "step_name": "kill_malware",
      "action": "kill_process",
      "status": "success",
      "target": "cryptolocker.exe",
      "duration_ms": 120,
      "next_step": "quarantine_files"
    },
    {
      "step_name": "quarantine_files",
      "action": "quarantine_file",
      "status": "success",
      "duration_ms": 89,
      "next_step": "notify_soc"
    },
    {
      "step_name": "notify_soc",
      "action": "webhook",
      "status": "success",
      "duration_ms": 230
    }
  ]
}

Chain execution statuses:

completed — all executed steps succeeded
partial — some steps succeeded, some failed (followed failure branches)
failed — no steps succeeded

Chains include loop protection — execution stops after steps × 3 iterations to prevent infinite cycles.