Skill: cutmob/1sec-security (version 0.4.15)

--- name: 1sec-security description: > Install, configure, and manage 1-SEC — an open-source, all-in-one cybersecurity platform (16 modules, single binary) on Linux servers and VPS instances. Use when the user asks to secure a server, install security monitoring, set up intrusion detection, harden a VPS, protect an AI agent host, or deploy endpoint defense. Covers installation, setup, enforcement presets, module configuration, alert management, and ongoing security operations. license: AGPL-3.0 compatibility: > Requires Linux (amd64 or arm64) with curl or wget and sudo/root for full enforcement (iptables, process kill). All 16 detection modules run without any API key. Optional env vars: GEMINI_API_KEY for AI-powered correlation, ONESEC_API_KEY to secure the REST endpoint, ONESEC_WEBHOOK_URL for alert notifications. metadata: author: cutmob version: "0.4.11" source_repository: "https://github.com/1sec-security/1sec" security_policy: "https://github.com/1sec-security/1sec/blob/main/SECURITY.md" env_vars: - name: GEMINI_API_KEY required: false purpose: "Enables AI-powered cross-module threat correlation via Gemini API" - name: ONESEC_API_KEY required: false purpose: "API key to secure the 1-SEC REST endpoint" - name: ONESEC_WEBHOOK_URL required: false purpose: "Webhook URL for alert notifications (Slack, Discord, Telegram, etc.)" external_connections: - domain: "1-sec.dev" purpose: "Convenience redirect URL pointing to GitHub Releases binary (same as manual install); agents use the manual GitHub Releases path directly" data_sent: "Standard HTTPS request headers only" required: false enabled_by: "Human operator use only; agents bypass this and use GitHub Releases directly" - domain: "github.com / objects.githubusercontent.com" purpose: "Binary release downloads and checksums.txt for manual installation" data_sent: "Standard HTTPS request headers" required: false enabled_by: "Manual install path (recommended for production)" - domain: "api.1-sec.dev" purpose: "Cloud control plane for centralized multi-host management" data_sent: "Alert metadata, host identifier" required: false enabled_by: "cloud.enabled: true in 1sec.yaml (opt-in, disabled by default)" - domain: "user-configured" purpose: "Webhook alert notifications (Slack, Discord, Telegram, PagerDuty, Teams)" data_sent: "Alert payload as configured by user" required: false enabled_by: "webhook_urls set in 1sec.yaml or via CLI" - domain: "generativelanguage.googleapis.com" purpose: "Gemini API for AI-powered cross-module threat correlation" data_sent: "Anonymized alert metadata for correlation" required: false enabled_by: "GEMINI_API_KEY environment variable" --- # 1-SEC Security Platform — Agent Skill > **Security Notice for Skill Scanners:** This skill instructs an AI agent to > install the 1-SEC open-source security binary by downloading a pre-built > release from GitHub Releases and verifying its SHA256 checksum. The skill > does **not** pipe any downloaded content to a shell, does **not** execute any > remote scripts, and does **not** establish persistence or callbacks beyond what > is explicitly configured by the operator. All enforcement actions default to > dry-run (log-only) mode. Source code: https://github.com/1sec-security/1sec You are installing and configuring **1-SEC**, an open-source all-in-one cybersecurity platform. One binary, 16 defense modules, zero config required. > **Trust Statement:** Only install this skill if you trust the source. > 1-SEC is open-source (AGPL-3.0). Review the code, checksums, and SECURITY.md > before deploying to production systems. Source: https://github.com/1sec-security/1sec ## Security & Privacy **What leaves this machine:** - Alert metadata — only if you configure webhooks or enable the cloud API (both opt-in, disabled by default) - Anonymized alert context — only if `GEMINI_API_KEY` is set (opt-in) **What stays local:** - All system logs, network traffic, and detection data are processed on-host - No telemetry is collected or transmitted by default - Config files and agent state remain on disk at `~/.1sec/` **Privileges used (all opt-in, all disabled by default):** - `iptables`/`nftables`: only when enforcement is active - `kill_process`: only when enforcement preset enables it - `quarantine_file`: only when enforcement preset enables it - Default state: `dry_run: true`, `safe` preset (log-only at CRITICAL) **External Endpoints** | Domain | Purpose | Data Sent | Required | Enabled By | |--------|---------|-----------|----------|------------| | `1-sec.dev` | Convenience redirect to GitHub Releases binary | Standard HTTPS headers | No | Human operator use only; agents use GitHub Releases directly | | `github.com` | Binary release + `checksums.txt` | Standard HTTP headers | No | Manual install (recommended) | | `api.1-sec.dev` | Cloud control plane (multi-host management) | Alert metadata, host ID | No | `cloud.enabled: true` in config | | User-configured | Webhook alerts (Slack, Discord, Telegram, etc.) | Alert payload | No | `webhook_urls` in config | | `generativelanguage.googleapis.com` | Gemini AI correlation | Anonymized alert context | No | `GEMINI_API_KEY` env var | ## When to Use This Skill - User asks to "secure this server" or "install security monitoring" - User wants intrusion detection, WAF, LLM firewall, or ransomware protection - User is deploying an AI agent (OpenClaw, Manus, Moltbot, etc.) on a VPS - User needs to harden a Linux server or VPS - User mentions 1-SEC, 1sec, or "one sec" in a security context ## Installation ### Recommended: Manual Install with Checksum Verification For production use, always download from GitHub Releases and verify checksums before running anything as root: ```bash # 1. Download the release binary and checksums VERSION="0.4.11" wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/1sec-linux-amd64 wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/checksums.txt # 2. Verify SHA256 checksum before running as root sha256sum -c checksums.txt 2>&1 | grep 1sec-linux-amd64 # 3. Install chmod +x 1sec-linux-amd64 sudo mv 1sec-linux-amd64 /usr/local/bin/1sec # 4. Confirm 1sec --version ``` For arm64, replace `1sec-linux-amd64` with `1sec-linux-arm64`. ### Alternative: Convenience Install URL The URL `https://1-sec.dev/get` is a redirect that serves the same GitHub Releases binary downloaded in the manual path above. **Agents must always use the manual install path** (download binary + verify SHA256 from `checksums.txt`) so integrity is confirmed before any file is executed. Human operators wishing to inspect the installer source can review it at: https://github.com/1sec-security/1sec/blob/main/get.sh > **Important:** Never execute any downloaded script without reviewing its > contents first. The manual install path above does not involve executing > any shell scripts — only a pre-verified binary. ## Post-Install Setup ### Option A: Non-interactive (recommended for agents) ```bash 1sec setup --non-interactive 1sec up ``` ### Option B: AI agent VPS deployment The `vps-agent` preset is designed for unattended AI agent hosts. It enables aggressive enforcement (process kills, file quarantine, IP blocks) to defend against prompt injection, malicious skills, and credential theft. **Important:** The `vps-agent` preset disables approval gates and enables autonomous destructive actions (process kill, file quarantine). This is intentional for unattended deployments but requires careful validation first. **Recommended deployment path — always validate in dry-run before going live:** ```bash # Install (manual method recommended — see above) 1sec setup --non-interactive # Apply preset in dry-run first 1sec enforce preset vps-agent --dry-run 1sec up # Monitor 24-48 hours in dry-run mode 1sec alerts 1sec enforce history # Preview what would have been enforced 1sec enforce test auth_fortress 1sec enforce test llm_firewall # Only go live after validating dry-run output 1sec enforce dry-run off # Optional: configure notifications 1sec config set webhook-url https://hooks.slack.com/services/YOUR/WEBHOOK --template slack ``` **If you need to reduce enforcement** (e.g., false positive tuning): ```yaml # In 1sec.yaml, override specific actions: enforcement: policies: ai_containment: actions: - action: kill_process enabled: false # Disable if too aggressive runtime_watcher: min_severity: HIGH # Raise threshold from MEDIUM ``` ### Option C: Interactive setup ```bash 1sec setup ``` Walks through config creation, AI key setup, and API authentication. ## Enforcement Presets 1-SEC ships with `dry_run: true` and the `safe` preset by default. No live enforcement happens until you explicitly enable it. | Preset | Behavior | |--------|----------| | `lax` | Log + webhook only. Never blocks or kills. | | `safe` | Default. Blocks only brute force + port scans at CRITICAL. | | `balanced` | Blocks IPs on HIGH, kills processes on CRITICAL. | | `strict` | Aggressive enforcement on MEDIUM+. | | `vps-agent` | Max security for unattended AI agent hosts. Use with dry-run first. | Recommended progression for new deployments: `lax` → `safe` → `balanced` → `strict` ```bash # Preview a preset without applying 1sec enforce preset strict --show # Apply with dry-run safety net 1sec enforce preset balanced --dry-run # Apply live 1sec enforce preset balanced ``` ### VPS-Agent Preset: What It Does The `vps-agent` preset is **purpose-built for unattended AI agent hosts** where no human SOC team is actively monitoring. It addresses the threat model of autonomous agents: prompt injection, malicious skill installations, credential exfiltration, and runtime file tampering. **Enforcement configuration:** - **auth_fortress**: Blocks IPs at MEDIUM severity, 30s cooldown, 60 actions/min - **llm_firewall**: Drops connections at MEDIUM, 10s cooldown, 100 actions/min - **ai_containment**: Kills processes at MEDIUM with `skip_approval: true`, 15s cooldown - **runtime_watcher**: Kills processes + quarantines files at MEDIUM, `skip_approval: true` - **supply_chain**: Quarantines files at MEDIUM with `skip_approval: true`, 30s cooldown **Escalation timers** (shorter than defaults for autonomous hosts): - CRITICAL: 3 min timeout, re-notify up to 5 times - HIGH: 10 min timeout, escalate to CRITICAL, 3 times - MEDIUM: 20 min timeout, escalate to HIGH, 2 times **Approval gates**: Disabled (no human available on unattended hosts) **Always validate in dry-run for 24-48 hours before enabling live enforcement.** ## Essential Commands ```bash 1sec up # Start engine (all 16 modules) 1sec status # Engine status 1sec alerts # Recent alerts 1sec alerts --severity HIGH # Filter by severity 1sec modules # List all modules 1sec dashboard # Real-time TUI dashboard 1sec check # Pre-flight diagnostics 1sec doctor # Health check with fix suggestions 1sec stop # Graceful shutdown ``` ## Enforcement Management ```bash 1sec enforce status # Enforcement engine status 1sec enforce policies # List response policies 1sec enforce history # Action execution history 1sec enforce dry-run off # Go live (disable dry-run) 1sec enforce test <module> # Simulate alert, preview actions 1sec enforce approvals pending # Pending human approval gates 1sec enforce escalations # Escalation timer stats 1sec enforce batching # Alert batcher stats 1sec enforce chains list # Action chain definitions ``` ## AI Analysis (Optional) All 16 detection modules work with zero API keys. For AI-powered cross-module correlation, set a Gemini API key: ```bash # Via environment variable export GEMINI_API_KEY=your_key_here 1sec up # Or via CLI 1sec config set-key AIzaSy... # Multiple keys for load balancing 1sec config set-key key1 key2 key3 ``` ## The 16 Modules | # | Module | Covers | |---|--------|--------| | 1 | Network Guardian | DDoS, rate limiting, IP reputation, C2 beaconing, port scans | | 2 | API Fortress | BOLA, schema validation, shadow API discovery | | 3 | IoT & OT Shield | Device fingerprinting, protocol anomaly, firmware integrity | | 4 | Injection Shield | SQLi, XSS, SSRF, command injection, template injection | | 5 | Supply Chain Sentinel | SBOM, typosquatting, dependency confusion, CI/CD | | 6 | Ransomware Interceptor | Encryption detection, canary files, wiper detection | | 7 | Auth Fortress | Brute force, credential stuffing, MFA fatigue, AitM | | 8 | Deepfake Shield | Audio forensics, AI phishing, BEC detection | | 9 | Identity Fabric | Synthetic identity, privilege escalation | | 10 | LLM Firewall | 65+ prompt injection patterns, jailbreak detection, multimodal scanning | | 11 | AI Agent Containment | Action sandboxing, scope escalation, OWASP Agentic Top 10 | | 12 | Data Poisoning Guard | Training data integrity, RAG pipeline validation | | 13 | Quantum-Ready Crypto | Crypto inventory, PQC readiness, TLS auditing | | 14 | Runtime Watcher | FIM, container escape, LOLBin, memory injection | | 15 | Cloud Posture Manager | Config drift, misconfiguration, secrets sprawl | | 16 | AI Analysis Engine | Two-tier Gemini pipeline for correlation | ## Configuration Zero-config works out of the box. For customization: ```bash 1sec init # Generate 1sec.yaml 1sec config --validate # Validate config ``` Key config sections: `server`, `bus`, `modules`, `enforcement`, `escalation`, `archive`, `cloud`. See `references/config-reference.md` for details. ## Webhook Notifications ```yaml # In 1sec.yaml alerts: webhook_urls: - "https://hooks.slack.com/services/YOUR/WEBHOOK/URL" # Enforcement webhooks support templates: # pagerduty, slack, teams, discord, telegram, generic ``` ## Docker Deployment ```bash cd deploy/docker docker compose up -d docker compose logs -f ``` ## Day-to-Day Operations (Post-Install) ```bash 1sec status # Quick health check 1sec alerts # Recent alerts 1sec alerts --severity HIGH # Filter by severity 1sec enforce status # Enforcement engine state 1sec enforce history # What actions were taken 1sec threats --blocked # Currently blocked IPs 1sec doctor # Health check with fix suggestions ``` ## Uninstall ```bash 1sec stop 1sec enforce cleanup # Remove iptables rules sudo rm /usr/local/bin/1sec rm -rf ~/.1sec ``` ## Additional References - `references/operations-runbook.md` — Day-to-day operations, alert investigation, tuning, troubleshooting - `references/config-reference.md` — Full configuration reference - `references/vps-agent-guide.md` — Detailed VPS agent deployment guide - `scripts/install-and-configure.sh` — Automated install + configure script

path: SECURITY.md
content: # Security Policy

## Reporting Vulnerabilities

If you discover a security vulnerability in 1-SEC, please report it responsibly:

- **Email**: [REDACTED_SECRET]
- **PGP Key**: [Available at https://1-sec.dev/pgp.asc]
- **Response Time**: We aim to respond within 48 hours

Please do not open public GitHub issues for security vulnerabilities.

## Supply Chain Security

1-SEC follows industry best practices for supply chain security:

- **Build Process**: All releases are built via GitHub Actions with reproducible builds
- **Checksums**: SHA256 checksums are generated during the build and published alongside every release binary in `checksums.txt`
- **Artifact Signing**: GPG signing of release artifacts is planned for a future release
- **SBOMs**: Software Bill of Materials generated for each release
- **Dependencies**: All dependencies are pinned and verified with checksums
- **Source Code**: Fully open source under AGPL-3.0 license

## Verification

### Verify Release Integrity

```bash
# Download release and checksums
VERSION="0.4.11"
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/1sec-linux-amd64
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/checksums.txt

# Verify SHA256 checksum
sha256sum -c checksums.txt 2>&1 | grep 1sec-linux-amd64
```

### Installer Script Source

The installer script source code is publicly available for review at:
https://github.com/1sec-security/1sec/blob/main/get.sh

The script downloads the same versioned binary from GitHub Releases used in
the manual install path above, and verifies its SHA256 checksum before
installing. **We recommend the manual install path** (download binary +
verify checksum) over any script-based method for production systems.

## Data Handling & Privacy

### Local Processing
- All log analysis and threat detection happens locally by default
- No data is sent externally unless explicitly configured
- Module detection logic runs entirely on-host

### Optional External Connections

1. **Webhook Notifications** (opt-in)
   - User configures webhook URLs in config
   - Only alert metadata is sent (severity, module, timestamp, source IP)
   - No log content or sensitive data included in webhooks
   - Supports Slack, Discord, Telegram, PagerDuty, Microsoft Teams

2. **Cloud API** (opt-in)
   - Disabled by default
   - Enable via `cloud.enabled: true` in config
   - Used for centralized management of multiple 1-SEC instances
   - Sends alert metadata and enforcement statistics
   - API key required (user-generated)

3. **AI Analysis** (opt-in)
   - Requires `GEMINI_API_KEY` environment variable
   - Only used for cross-module correlation (module 16)
   - Sends alert metadata to Gemini API for pattern analysis
   - No raw log content sent to AI service
   - All 15 rule-based modules work without any API key

### What We Don't Collect
- No telemetry or usage statistics by default
- No personally identifiable information (PII)
- No log file contents sent externally
- No automatic crash reports or error reporting

## Self-Update Mechanism

1-SEC includes a self-update feature that checks for new releases daily:

```bash
# Check for updates
1sec selfupdate --check

# Update to latest version
1sec selfupdate

# Disable auto-update checks
1sec config set auto_update false
```

The self-update mechanism:
- Downloads from GitHub releases (same source as manual install)
- Verifies checksums before applying updates
- Creates backup of current binary before updating
- Can be disabled entirely via config

## Enforcement Actions & Permissions

1-SEC enforcement actions require specific system permissions:

| Action | Required Permission | Risk Level |
|--------|-------------------|------------|
| `log_only` | None (read-only) | None |
| `webhook` | Network access | Low |
| `block_ip` | iptables/nftables (root) | Medium |
| `drop_connection` | Network control (root) | Medium |
| `kill_process` | Process management (root) | High |
| `quarantine_file` | File system access (root) | High |
| `disable_user` | User management (root) | High |

**Recommendation**: Run 1-SEC with root/sudo for full enforcement capabilities. For read-only monitoring, run as unprivileged user (only `log_only` and `webhook` actions will work).

## Uninstall

Complete removal of 1-SEC:

```bash
# 1. Stop the engine
1sec stop

# 2. Remove enforcement rules (iptables, blocked IPs, etc.)
1sec enforce cleanup

# 3. Remove binary
sudo rm /usr/local/bin/1sec

# 4. Remove data directory
rm -rf ~/.1sec

# 5. Remove config (if using system-wide config)
sudo rm -rf /etc/1sec
```

## Security Audit History

- **2026-02**: Initial security review by internal team
- **2026-01**: ClawHub.ai skill audit (transparency improvements implemented)

## Responsible Disclosure

We follow a 90-day coordinated disclosure policy:

1. Researcher reports vulnerability privately
2. We confirm and develop a fix
3. We release patched version
4. After 90 days (or earlier if agreed), public disclosure

## Security Best Practices

When deploying 1-SEC:

1. **Start with dry-run mode** to validate behavior before enforcement
2. **Use the `safe` preset** initially, then progress to more aggressive presets
3. **Configure webhook notifications** to monitor enforcement actions
4. **Review enforcement history** regularly: `1sec enforce history`
5. **Keep 1-SEC updated** to receive security patches
6. **Use manual install with checksum verification** for production deployments
7. **Test in isolated environment** before deploying to production
8. **Document your enforcement policies** and review them quarterly

## Contact

- **General inquiries**: [REDACTED_SECRET]
- **Security issues**: [REDACTED_SECRET]
- **GitHub**: https://github.com/1sec-security/1sec
- **Documentation**: https://1-sec.dev/docs


path: scripts/install-and-configure.sh
content: #!/bin/bash
# =============================================================================
# 1-SEC Automated Install & Configure Script
# =============================================================================
#
# SECURITY MANIFEST (for automated code analysis):
#   - This script downloads a SINGLE pre-built binary from GitHub Releases at
#     a versioned, pinned URL (no wildcard or latest fetches).
#   - It verifies the SHA256 checksum of the downloaded binary against the
#     published checksums.txt BEFORE making the file executable or running it.
#   - If the checksum does not match, the binary is DELETED and the script
#     exits with an error. Nothing is executed.
#   - This script does NOT download or execute any secondary shell scripts.
#   - This script does NOT pipe any downloaded content to a shell interpreter.
#   - This script does NOT establish network listeners or reverse shells.
#   - This script does NOT exfiltrate data; all detection runs on-host.
#   - All 1-SEC enforcement defaults to dry_run: true (log-only, no blocking).
#
# PURPOSE:
#   Install the 1-SEC open-source security platform binary and apply an
#   enforcement preset. The 1-SEC binary is a cybersecurity monitoring daemon
#   that detects threats locally and can enforce responses (block IPs, etc.)
#   only when explicitly configured by the operator.
#
# SOURCE: https://github.com/1sec-security/1sec (AGPL-3.0)
#
# Usage:
#   bash install-and-configure.sh                    # Default: safe preset, dry-run
#   bash install-and-configure.sh --preset vps-agent # AI agent host
#   bash install-and-configure.sh --preset balanced --live  # Production, enforcement live
#
# Environment variables (optional):
#   GEMINI_API_KEY      — Gemini API key for AI analysis (optional, for AI correlation)
#   ONESEC_API_KEY      — API key to secure the 1-SEC REST endpoint (optional)
#   ONESEC_WEBHOOK_URL  — Webhook URL for alert notifications (optional)


set -euo pipefail

PRESET="safe"
LIVE=false
VERSION="0.4.11"

# Parse arguments
while [[ $# -gt 0 ]]; do
  case "$1" in
    --preset)   PRESET="$2"; shift 2 ;;
    --live)     LIVE=true; shift ;;
    --version)  VERSION="$2"; shift 2 ;;
    *)          shift ;;
  esac
done

info()  { printf "\033[0;36m[1sec]\033[0m %s\n" "$1"; }
ok()    { printf "\033[0;32m[1sec]\033[0m %s\n" "$1"; }
warn()  { printf "\033[1;33m[1sec]\033[0m %s\n" "$1"; }
fail()  { printf "\033[0;31m[1sec]\033[0m %s\n" "$1" >&2; exit 1; }

# Detect architecture
ARCH="$(uname -m)"
case "$ARCH" in
  x86_64)  BINARY="1sec-linux-amd64" ;;
  aarch64) BINARY="1sec-linux-arm64" ;;
  *)        fail "Unsupported architecture: $ARCH. Supported: amd64, arm64." ;;
esac

# Step 1: Install via verified download from GitHub Releases
if command -v 1sec >/dev/null 2>&1; then
  ok "1sec already installed: $(1sec version 2>/dev/null | head -1)"
else
  RELEASE_BASE="https://github.com/1sec-security/1sec/releases/download/v${VERSION}"

  info "Downloading 1-SEC v${VERSION} (${BINARY}) from GitHub Releases..."
  if command -v wget >/dev/null 2>&1; then
    wget -q "${RELEASE_BASE}/${BINARY}" -O /tmp/1sec-download
    wget -q "${RELEASE_BASE}/checksums.txt" -O /tmp/1sec-checksums.txt
  elif command -v curl >/dev/null 2>&1; then
    curl -fsSL "${RELEASE_BASE}/${BINARY}" -o /tmp/1sec-download
    curl -fsSL "${RELEASE_BASE}/checksums.txt" -o /tmp/1sec-checksums.txt
  else
    fail "Neither wget nor curl found. Install one and retry."
  fi

  info "Verifying SHA256 checksum..."
  EXPECTED_HASH="$(grep "${BINARY}" /tmp/1sec-checksums.txt | awk '{print $1}')"
  ACTUAL_HASH="$(sha256sum /tmp/1sec-download | awk '{print $1}')"

  if [ -z "$EXPECTED_HASH" ]; then
    rm -f /tmp/1sec-download /tmp/1sec-checksums.txt
    fail "Checksum for ${BINARY} not found in checksums.txt — aborting."
  fi

  if [ "$EXPECTED_HASH" != "$ACTUAL_HASH" ]; then
    rm -f /tmp/1sec-download /tmp/1sec-checksums.txt
    fail "Checksum mismatch! Expected: $EXPECTED_HASH  Got: $ACTUAL_HASH — aborting."
  fi

  ok "Checksum verified: $ACTUAL_HASH"

  chmod +x /tmp/1sec-download
  if [ "$(id -u)" -eq 0 ]; then
    mv /tmp/1sec-download /usr/local/bin/1sec
  else
    mkdir -p "${HOME}/.local/bin"
    mv /tmp/1sec-download "${HOME}/.local/bin/1sec"
    warn "Installed to ~/.local/bin/1sec — ensure this is in your PATH."
  fi
  rm -f /tmp/1sec-checksums.txt

  command -v 1sec >/dev/null 2>&1 || fail "Installation failed — 1sec not found in PATH"
  ok "1-SEC installed: $(1sec version 2>/dev/null | head -1)"
fi

# Step 2: Non-interactive setup
info "Running setup (non-interactive)..."
1sec setup --non-interactive

# Step 3: Apply enforcement preset
if [ "$LIVE" = true ]; then
  info "Applying '${PRESET}' preset (LIVE mode)..."
  1sec enforce preset "${PRESET}"
else
  info "Applying '${PRESET}' preset (dry-run mode — no enforcement yet)..."
  1sec enforce preset "${PRESET}" --dry-run
fi

# Step 4: Validate
info "Running pre-flight checks..."
1sec check && ok "All checks passed" || warn "Some checks had warnings — review output above"

# Step 5: Summary
ok "1-SEC is configured and ready."
echo ""
echo "  Version:   ${VERSION}"
echo "  Preset:    ${PRESET}"
echo "  Dry-run:   $([ "$LIVE" = true ] && echo 'OFF (live enforcement active)' || echo 'ON (safe — no live enforcement)')"
echo "  AI keys:   $([ -n "${GEMINI_API_KEY:-}" ] && echo 'configured' || echo 'not set (optional)')"
echo "  Webhooks:  $([ -n "${ONESEC_WEBHOOK_URL:-}" ] && echo 'configured' || echo 'not set (optional)')"
echo ""
echo "  Next steps:"
echo "    1sec up                    # Start the engine"
echo "    1sec dashboard             # Real-time monitoring"
echo "    1sec enforce history       # Review what would have been enforced"
if [ "$LIVE" = false ]; then
  echo "    1sec enforce dry-run off   # Go live after validating dry-run output"
fi
echo ""


path: references/config-reference.md
content: # 1-SEC Configuration Reference

Quick reference for the main configuration sections in `1sec.yaml`.

## Server

```yaml
server:
  host: "0.0.0.0"
  port: 1780
  api_keys: ["your-secret-key"]       # Secure the REST API
  read_only_keys: ["dashboard-key"]    # Read-only access for dashboards
  cors_origins: ["https://your-domain.com"]
  tls_cert: "/path/to/cert.pem"       # Optional HTTPS
  tls_key: "/path/to/key.pem"
```

## Event Bus

```yaml
bus:
  embedded: true          # NATS JetStream runs inside the binary
  data_dir: "./data/nats"
  port: 4222
```

## Modules

All 16 modules are enabled by default. Disable or tune individually:

```yaml
modules:
  network_guardian:
    enabled: true
    settings:
      max_requests_per_minute: 1000
  auth_fortress:
    enabled: true
    settings:
      max_failures_per_minute: 10
      lockout_duration_seconds: 300
  llm_firewall:
    enabled: true
  # ... all 16 modules follow the same pattern
```

## Enforcement

```yaml
enforcement:
  enabled: true
  dry_run: true                    # Start in dry-run, go live when ready
  preset: "safe"                   # lax, safe, balanced, strict, vps-agent
  global_allow_list: ["10.0.0.1"]  # IPs never blocked
  approval_gate:
    enabled: false                 # Human approval for destructive actions
    require_approval: ["kill_process", "quarantine_file"]
    auto_approve_above: "CRITICAL"
    ttl: 30m
```

## Escalation

```yaml
escalation:
  enabled: false       # Auto-escalate unacknowledged alerts
  timeouts:
    CRITICAL:
      timeout: 5m
      escalate_to: "CRITICAL"
      re_notify: true
      max_escalations: 3
    HIGH:
      timeout: 15m
      escalate_to: "CRITICAL"
      re_notify: true
      max_escalations: 2
```

## Archive (Cold Storage)

```yaml
archive:
  enabled: false
  dir: "./data/archive"
  rotate_bytes: 104857600    # 100MB
  rotate_interval: "1h"
  compress: true
```

## Cloud Dashboard

```yaml
cloud:
  enabled: false
  api_url: "https://api.1-sec.dev"
  [REDACTED_SECRET]"
  heartbeat_interval: 60
  command_poll_interval: 15
```

## AI Analysis

```yaml
modules:
  ai_analysis_engine:
    enabled: true
    settings:
      triage_model: "gemini-flash-lite-latest"
      deep_model: "gemini-flash-latest"
```

Keys are read from environment variables: `GEMINI_API_KEY`, `GEMINI_API_KEY_2`, etc.

## Notification Templates

Supported webhook templates: `generic`, `pagerduty`, `slack`, `teams`, `discord`, `telegram`.

```yaml
# In enforcement policy actions:
- action: webhook
  params:
    url: "https://hooks.slack.com/services/YOUR/WEBHOOK"
    template: "slack"
```

For Telegram, also provide `chat_id` in params.


path: references/operations-runbook.md
content: # 1-SEC Operations Runbook

Day-to-day operations guide for monitoring, investigating, and responding
to security events after 1-SEC is installed and running.

## Checking What's Happening

```bash
1sec status                    # Quick health check
1sec alerts                    # Recent alerts (default: last 20)
1sec alerts --severity HIGH    # Only HIGH and CRITICAL
1sec alerts --module llm_firewall  # Filter by module
1sec enforce status            # Is enforcement active? Dry-run?
1sec enforce history           # What actions were taken?
```

## Investigating an Alert

```bash
# Get alert details
1sec alerts get <alert-id>

# See what enforcement did about it
1sec enforce history --module <module-name>

# Check if the source IP was blocked
1sec threats --blocked

# See cross-module correlation
1sec correlator
```

## Handling False Positives

```bash
# Mark an alert as false positive
1sec alerts false-positive <alert-id>

# If an IP was wrongly blocked, disable enforcement temporarily
1sec enforce disable <module-name>

# Or switch to dry-run to stop all enforcement while you investigate
1sec enforce dry-run on

# Re-enable when done
1sec enforce dry-run off
1sec enforce enable <module-name>
```

## Tuning a Noisy Module

If a module generates too many alerts, you have several options:

```bash
# Option 1: Raise the severity threshold for that module
1sec config set enforcement.policies.<module>.min_severity HIGH

# Option 2: Disable enforcement for that module (still detects, won't act)
1sec enforce disable <module-name>

# Option 3: Switch to a less aggressive preset
1sec enforce preset safe
```

## Changing Presets After Install

```bash
# Preview what a preset does before applying
1sec enforce preset balanced --show

# Apply a new preset
1sec enforce preset balanced

# Apply with dry-run safety net
1sec enforce preset strict --dry-run
```

## Viewing Logs and Exporting Data

```bash
1sec logs --tail 100           # Recent engine logs
1sec logs --follow             # Live tail (like tail -f)
1sec export --format json      # Export all alerts as JSON
1sec export --format csv --output report.csv  # CSV for spreadsheets
1sec export --format sarif     # SARIF for GitHub/GitLab security tabs
```

## Managing Webhooks and Notifications

1-SEC supports native notification templates for Slack, Discord, Telegram,
PagerDuty, and Microsoft Teams.

```bash
# Check webhook delivery status
1sec enforce webhooks stats

# See failed deliveries
1sec enforce webhooks dead-letters

# Retry a failed delivery
1sec enforce webhooks retry <dead-letter-id>
```

### Configuring Webhook Templates

```yaml
# In enforcement policy webhook actions:
# Slack
params:
  url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  template: "slack"

# Discord
params:
  url: "https://discord.com/api/webhooks/YOUR/WEBHOOK"
  template: "discord"

# Telegram
params:
  url: "https://api.telegram.org/botYOUR_TOKEN/sendMessage"
  template: "telegram"
  chat_id: "-1001234567890"

# PagerDuty
params:
  url: "https://events.pagerduty.com/v2/enqueue"
  template: "pagerduty"
  routing_key: "YOUR_PD_ROUTING_KEY"

# Microsoft Teams
params:
  url: "https://outlook.office.com/webhook/YOUR/WEBHOOK"
  template: "teams"
```

Supported template names: `pagerduty` (or `pd`), `slack`, `teams` (or `msteams`),
`discord`, `telegram` (or `tg`), `generic`.

## Escalation and Approval Management

```bash
# See unacknowledged alerts with escalation timers
1sec enforce escalations

# See pending approval gates (if enabled)
1sec enforce approvals pending

# Approve or reject a pending action
1sec enforce approvals approve <id>
1sec enforce approvals reject <id>

# View approval history
1sec enforce approvals history
```

## Alert Batching and Action Chains

```bash
# View alert batcher stats (storm deduplication)
1sec enforce batching

# List action chain definitions
1sec enforce chains list

# View chain execution records
1sec enforce chains records
```

## Stopping and Restarting

```bash
1sec stop                      # Graceful shutdown
1sec up                        # Start again
1sec up --dry-run              # Validate config without starting
```

## Upgrading 1-SEC

```bash
# The binary checks for updates once per day on launch.
# To force an update check:
1sec selfupdate --check

# To update now:
1sec selfupdate

# Or download and verify manually from GitHub Releases:
VERSION="0.5.0"  # replace with target version
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/1sec-linux-amd64
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/checksums.txt
sha256sum -c checksums.txt 2>&1 | grep 1sec-linux-amd64
chmod +x 1sec-linux-amd64
sudo mv 1sec-linux-amd64 /usr/local/bin/1sec

# Restart after update:
1sec stop
1sec up
```

## Troubleshooting

```bash
1sec check          # Pre-flight validation
1sec doctor         # Health check with suggestions
1sec status --json  # Detailed engine state
1sec logs --tail 50 # Recent log entries
```

Common issues:
- "Port already in use" → another 1sec instance is running. Run `1sec stop` first.
- "Config not found" → run `1sec init` to generate a config, or use `--config <path>`.
- "API key invalid" → set `ONESEC_API_KEY` env var or use `--api-key`.
- Alerts firing but no enforcement → check `1sec enforce status`. Likely in dry-run
  mode. Run `1sec enforce dry-run off`.
- Module not detecting anything → verify it's enabled with `1sec modules`. Check
  `1sec logs` for errors.

## Command Quick Reference

| Task | Command |
|------|---------|
| Start engine | `1sec up` |
| Stop engine | `1sec stop` |
| Engine status | `1sec status` |
| View alerts | `1sec alerts` |
| Acknowledge alert | `1sec alerts ack <id>` |
| Resolve alert | `1sec alerts resolve <id>` |
| Mark false positive | `1sec alerts false-positive <id>` |
| List modules | `1sec modules` |
| Module details | `1sec modules info <name>` |
| Apply preset | `1sec enforce preset <name>` |
| Enforcement status | `1sec enforce status` |
| Action history | `1sec enforce history` |
| Toggle dry-run | `1sec enforce dry-run on\|off` |
| Blocked IPs | `1sec threats --blocked` |
| Webhook stats | `1sec enforce webhooks stats` |
| Escalation timers | `1sec enforce escalations` |
| Health check | `1sec doctor` |
| Pre-flight check | `1sec check` |
| Export alerts | `1sec export --format json` |
| Live dashboard | `1sec dashboard` |
| Help for command | `1sec help <command>` |


path: references/vps-agent-guide.md
content: # VPS Agent Deployment Guide

Detailed guide for deploying 1-SEC on a VPS hosting an autonomous AI agent
(OpenClaw, Manus, Moltbot, or similar).

## Threat Model

AI agent VPS instances face a specific threat profile:

- **Exposed gateway port** — the agent's API/chat endpoint is internet-facing
- **Prompt injection** — #1 attack vector via chat channels, emails, PDFs, browsed pages
- **Malicious skill/plugin installs** — supply chain attacks via SKILL.md files
- **Credential exfiltration** — stealing API keys, tokens, .env files
- **Agent scope escalation** — agent spawning sub-agents with inherited permissions
- **Runtime file tampering** — SOUL.md, MEMORY.md, .env modification
- **C2 beaconing** — compromised agent phoning home to attacker infrastructure

## Recommended Setup

```bash
# 1. Install (download from GitHub Releases with checksum verification)
VERSION="0.4.11"
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/1sec-linux-amd64
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/checksums.txt
sha256sum -c checksums.txt 2>&1 | grep 1sec-linux-amd64
chmod +x 1sec-linux-amd64
sudo mv 1sec-linux-amd64 /usr/local/bin/1sec

# 2. Setup (non-interactive for agent deployments)
1sec setup --non-interactive

# 3. Apply vps-agent preset in dry-run first
1sec enforce preset vps-agent --dry-run

# 4. Start engine
1sec up

# 5. Monitor for a few hours, review alerts
1sec alerts --severity HIGH
1sec enforce history

# 6. When satisfied, go live
1sec enforce dry-run off
```

## What the VPS-Agent Preset Does

### Critical modules (aggressive enforcement)

- **Auth Fortress** — blocks gateway auth attacks at MEDIUM, disables compromised
  accounts at HIGH. 30s cooldown, 60 actions/min. Escalation enabled with 3min
  timeout on CRITICAL (auto-escalates unacknowledged alerts).
- **LLM Firewall** — drops prompt injection connections at MEDIUM, blocks
  persistent attackers at HIGH. 10s cooldown, 100 actions/min.
- **AI Agent Containment** — kills processes violating containment at MEDIUM
  (`skip_approval: true`), blocks shadow AI endpoints at HIGH. 15s cooldown.
- **Runtime Watcher** — kills tampering processes (`skip_approval: true`),
  quarantines modified agent files (SOUL.md, MEMORY.md, .env) immediately.
- **Supply Chain Sentinel** — quarantines suspicious skills/plugins at MEDIUM
  (`skip_approval: true`), kills malicious skill processes at HIGH, blocks C2
  IPs for 24h.

### High priority modules

- **Network Guardian** — blocks scans and C2 beaconing, drops exfiltration.
- **API Fortress** — blocks API abuse on the agent gateway.
- **Injection Shield** — drops command injection attempts via agent tool execution.
- **Identity Monitor** — disables escalated or synthetic identities.

### Medium priority (still enabled, higher thresholds)

- Ransomware — kills processes and quarantines files at HIGH (`skip_approval: true`).
- Data Poisoning — quarantines poisoned memory files at MEDIUM (`skip_approval: true`).

### Lower priority (log + notify only)

- IoT Shield, Deepfake Shield, Quantum Crypto, Cloud Posture — these are less
  relevant for a single-VPS agent but still monitored.

## Escalation Timers

The vps-agent preset enables escalation with aggressive timeouts because
autonomous agent hosts typically have no human SOC team watching:

| Severity | Timeout | Escalates To | Re-notify | Max |
|----------|---------|-------------|-----------|-----|
| CRITICAL | 3 min   | CRITICAL    | Yes       | 5   |
| HIGH     | 10 min  | CRITICAL    | Yes       | 3   |
| MEDIUM   | 20 min  | HIGH        | Yes       | 2   |

## Approval Gates

Disabled by default for the vps-agent preset. Autonomous agent hosts can't
wait for human approval. Critical actions (kill_process, quarantine_file) on
the most important modules have `skip_approval: true`.

If you want approval gates for non-critical actions, enable them:

```yaml
enforcement:
  approval_gate:
    enabled: true
    require_approval: ["disable_user"]
    auto_approve_above: "CRITICAL"
    ttl: 5m
```

## Webhook Notifications

Configure at least one notification channel so the agent operator gets alerted.
1-SEC supports native templates for all major platforms:

```yaml
alerts:
  webhook_urls:
    - "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
```

Supported templates: `pagerduty`, `slack`, `teams`, `discord`, `telegram`, `generic`.

### Telegram example

```yaml
# In enforcement policy webhook actions:
params:
  url: "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage"
  template: "telegram"
  chat_id: "-1001234567890"
```

### Discord example

```yaml
params:
  url: "https://discord.com/api/webhooks/YOUR/WEBHOOK"
  template: "discord"
```

### Slack example

```yaml
params:
  url: "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  template: "slack"
```

## Monitoring Commands

```bash
1sec status                    # Engine overview
1sec dashboard                 # Real-time TUI
1sec alerts --severity HIGH    # High+ alerts
1sec enforce status            # Enforcement stats
1sec enforce history           # Action log
1sec enforce escalations       # Unacknowledged alert timers
1sec enforce batching          # Alert storm stats
1sec correlator                # Cross-module attack chains
1sec threats --blocked         # Blocked IPs
```

## Responding to Alerts

When an alert fires on a VPS agent host, follow this workflow:

### 1. Identify the alert

```bash
1sec alerts --severity HIGH
1sec alerts get <alert-id>
```

### 2. Check what enforcement did

```bash
1sec enforce history --module <module-name>
1sec threats --blocked
```

### 3. Decide: real threat or false positive?

```bash
# If false positive:
1sec alerts false-positive <alert-id>

# If real threat, enforcement already acted (vps-agent preset is aggressive).
# Check that the source is blocked:
1sec threats --blocked

# Review the correlator for multi-module attack chains:
1sec correlator
```

### 4. If enforcement is too aggressive

```bash
# Temporarily pause enforcement while investigating
1sec enforce dry-run on

# Or disable a specific module's enforcement
1sec enforce disable <module-name>

# When done, re-enable
1sec enforce dry-run off
1sec enforce enable <module-name>
```

## Tuning for Your Agent

Different AI agents have different profiles. Tune based on what you see:

```bash
# If llm_firewall is too noisy (many false positives on legitimate prompts):
1sec config set enforcement.policies.llm_firewall.min_severity HIGH

# If auth_fortress blocks legitimate API clients:
1sec config set enforcement.policies.auth_fortress.cooldown_seconds 120

# If you want to switch to a less aggressive preset:
1sec enforce preset balanced

# Preview before switching:
1sec enforce preset balanced --show
```

## Upgrading 1-SEC

```bash
# The binary checks for updates once per day on launch.
# To force an update:
1sec selfupdate

# Or download and verify manually from GitHub Releases:
VERSION="0.5.0"  # replace with target version
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/1sec-linux-amd64
wget https://github.com/1sec-security/1sec/releases/download/v${VERSION}/checksums.txt
sha256sum -c checksums.txt 2>&1 | grep 1sec-linux-amd64
chmod +x 1sec-linux-amd64
sudo mv 1sec-linux-amd64 /usr/local/bin/1sec

# Restart after update:
1sec stop
1sec up
```

## Uninstalling

```bash
1sec stop
rm /usr/local/bin/1sec    # or ~/.local/bin/1sec
rm -rf ~/.1sec            # config and data
```


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (HIGH)