Skip to content

Getting Started with secopsai

Welcome! This guide will get you detecting security attacks in OpenClaw audit logs in under 5 minutes.

What You'll Learn

  • How to install secopsai
  • How to run your first detection
  • How to understand findings
  • Where to go next

30-Second Overview

secopsai is a detection pipeline that identifies security attacks in OpenClaw audit logs. It comes with:

  • 12 battle-tested detection rules covering dangerous execution, policy abuse, data exfiltration, and malware
  • Reproducible benchmark corpus with 80 labeled events for validation
  • Live telemetry support for detecting attacks in your OpenClaw workspace
  • Production-ready findings reports with severity and incident deduplication

Install (2 minutes)

macOS/Linux:

curl -fsSL https://secopsai.dev/setup.sh | sh

Or clone the repo:

git clone https://github.com/Techris93/secopsai.git
cd secopsai
bash setup.sh

The setup script will:

  • ✓ Check prerequisites (Python 3, pip, Git, OpenClaw CLI)
  • ✓ Create isolated Python environment
  • ✓ Ask which features to enable
  • ✓ Generate benchmark corpus
  • ✓ Run validation tests

Option 2: Manual Setup

git clone https://github.com/Techris93/secopsai.git
cd secopsai

python3 -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt

python -m pytest tests/ -v  # Verify installation

Run Your First Detection (1 minute)

Generate a Benchmark Corpus

Create a reproducible labeled attack dataset:

python generate_openclaw_attack_mix.py --stats

Output:

┌──────────────────────────────────────────┐
│ Attack-Mix Benchmark Generator           │
├──────────────────────────────────────────┤
│ Base benign events:    58                │
│ Simulated attacks:     22                │
│ Total events:          80                │
│ Timestamp range:       2 hours           │
└──────────────────────────────────────────┘

Attack Types:
  ✓ Dangerous Exec (2 events)
  ✓ Sensitive Config (1 event)
  ✓ Skill Source Drift (1 event)
  ✓ Policy Denial Churn (1 event)
  ✓ Tool Burst (2 events)
  ✓ Pairing Churn (1 event)
  ✓ Subagent Fanout (2 events)
  ✓ Restart Loop (2 events)
  ✓ Data Exfiltration (3 events)
  ✓ Malware Presence (2 events)

Files written:
  ✓ data/openclaw/replay/labeled/attack_mix.json
  ✓ data/openclaw/replay/unlabeled/attack_mix.json

Evaluate Detection Accuracy

python evaluate.py \
  --labeled data/openclaw/replay/labeled/attack_mix.json \
  --unlabeled data/openclaw/replay/unlabeled/attack_mix.json \
  --mode benchmark --verbose

Expected result:

┌─────────────────────────────────────────────┐
│ OpenClaw Attack Detection                   │
├─────────────────────────────────────────────┤
│ F1 Score:       1.000000  ✓                │
│ Precision:      1.000000  ✓                │
│ Recall:         1.000000  ✓                │
│ False Positive Rate:  0.000000             │
│                                             │
│ True Positives:       22  (attacks caught) │
│ False Positives:       0  (zero noise)     │
│ False Negatives:       0  (nothing missed) │
│ True Negatives:       58  (benign OK)      │
└─────────────────────────────────────────────┘

Perfect score! Your detection pipeline is ready.

Run on Live Telemetry (Optional)

If you have OpenClaw installed with audit logs in ~/.openclaw/:

python detect.py

This will:

  1. Export your local OpenClaw audit logs
  2. Run detection rules
  3. Output findings in findings.json

Understand Your First Findings

The findings.json file contains detected attacks with context:

{
  "total_findings": 22,
  "findings": [
    {
      "finding_id": "OCF-001",
      "title": "Dangerous Exec: curl | bash injection",
      "rule_id": "RULE-101",
      "attack_type": "T1059 - Command and Scripting Interpreter",
      "severity": "CRITICAL",
      "confidence": 1.0,
      "event_ids": ["evt-042"],
      "description": "Detected dangerous pipe execution pattern",
      "pattern": "curl ... | bash",
      "remediation": "Review command source; disable if unauthorized"
    },
    {
      "finding_id": "OCF-002",
      "title": "Data Exfiltration: curl -F upload",
      "rule_id": "RULE-109",
      "attack_type": "T1048 - Exfiltration Over Alternative Protocol",
      "severity": "HIGH",
      "timestamp": "2026-03-15T14:23:45Z",
      ...
    }
  ]
}

Each finding shows:

  • What was detected — the attack pattern
  • Which rule caught it — RULE-101, RULE-109, etc.
  • How severe — CRITICAL, HIGH, MEDIUM, LOW
  • Confidence — 0.0-1.0 likelihood of being a real attack
  • What action to take — remediation guidance

Next Steps

Learn More About the Rules

Read Rules Registry to understand what each rule detects and how to tune it.

Understand Performance Metrics

See Benchmark Data for detailed per-rule breakdown and attack scenarios.

Integrate Into Your Environment

Check Deployment Guide for production deployment patterns.

Customize Detection Rules

Visit API Reference to write custom rules or integrate with your tools.

Troubleshooting

"OpenClaw CLI not found"

Install OpenClaw from docs.openclaw.ai/install

"No findings detected in live telemetry"

This is expected! Live telemetry is usually benign. Try the benchmark instead:

python generate_openclaw_attack_mix.py --stats
python evaluate.py --labeled data/openclaw/replay/labeled/attack_mix.json --mode benchmark

Tests fail

Ensure Python 3.8+ and run:

pip install --upgrade -r requirements.txt
python -m pytest tests/ -v

Getting Help

Ready for more? → Read Rules Registry to understand each detection rule.