OpenClaw Integration (Conversational SecOps)

New: SecOpsAI is now available as a native OpenClaw plugin with TypeScript-based tools. This guide covers the Python CLI approach; for the plugin approach, see OpenClaw Native Plugin.

This guide shows how to wire secopsai into an existing OpenClaw deployment using the real Python CLIs:

• run_openclaw_live.py — live detection pipeline
• soc_store.py — findings store and triage
• openclaw_plugin.py — high-level malware/exfil/mitigation checks

---

1. Install secopsai

Run the one-line install on the same machine as your OpenClaw gateway:

curl -fsSL https://secopsai.dev/install.sh | bash

The public npm package provides the OpenClaw plugin. It does not replace the Core Python installation above:

openclaw plugins install secopsai

Fallback (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 prepare.py  # Generate data/events.json and data/events_unlabeled.json
python -m pytest tests/ -v  # Optional: verify installation

From now on, activate the virtualenv before running any commands:

cd secopsai
source .venv/bin/activate

---

2. Run the OpenClaw live pipeline (CLI-first)

Recommended entrypoint is the secopsai CLI, which runs the same five steps in-process and writes structured metadata about the refresh.

# Full live run (export + ingest + prepare + detect + findings)
secopsai refresh

# If you have already exported from ~/.openclaw and just want to re-run
# ingest/prepare/detect/findings, skip the export step:
secopsai refresh --skip-export

# For automation/integrations, use JSON output:
secopsai refresh --json

Under the hood this runs the same sequence as before:

1. export_real_openclaw_native.py — pulls telemetry from ~/.openclaw
2. ingest_openclaw.py — normalises into an audit stream
3. openclaw_prepare.py — builds replay bundles
4. evaluate_openclaw.py — runs detectors in live mode
5. openclaw_findings.py — writes findings (with mitigations) into the local SOC store (the hosted dashboard reads findings from Cloudflare D1; the legacy Supabase sync below is skipped when no Supabase project is configured, which is the default since Supabase was retired in October 2026).

Automatic dashboard sync is intentionally safe and optional:

• Enabled by configuration presence: SUPABASE_URL plus either SUPABASE_SERVICE_ROLE_KEY or SUPABASE_ANON_KEY
• Credentials can come from the current environment or from the default dashboard env file at ../secopsai-dashboard/.env
• Schema mapping is validated against the dashboard findings migration by default
• If credentials are missing, the refresh/pipeline still succeeds and sync is skipped
• If sync fails after findings are persisted locally, the local pipeline still completes; the sync error is printed for operator visibility
• Upserts are idempotent by external_finding_id

You can still call the script directly if needed:

python run_openclaw_live.py
python run_openclaw_live.py --skip-export
secopsai sync-findings --dry-run

At the end, inspect the findings store:

secopsai list --severity high
# or, for raw store listing
python soc_store.py list

---

3. Inspect and triage findings (soc_store CLI)

Security note: triage operations modify the local SOC store (SQLite). If you are running secopsai via an agent, prefer read-only operations by default and require explicit user confirmation before any triage/write action.

List all findings:

python soc_store.py list

Example output:

OCF-62FA8D1D3578BF6E | HIGH     | status=open    | disposition=unreviewed   | OpenClaw Sensitive Config
OCF-C9D2523C770B6731 | HIGH     | status=open    | disposition=unreviewed   | OpenClaw Dangerous Exec / OpenClaw Tool Burst
OCF-478C69DCE3A33CC7 | INFO     | status=triaged | disposition=true_positive | OpenClaw Data Exfiltration
total_findings=14

Show a single finding in full:

python soc_store.py show OCF-62FA8D1D3578BF6E

Triage:

# Mark disposition
python soc_store.py set-disposition OCF-62FA8D1D3578BF6E true_positive

# Update status
python soc_store.py set-status OCF-62FA8D1D3578BF6E triaged

# Add analyst note
python soc_store.py add-note OCF-62FA8D1D3578BF6E analyst "validated via manual review"

---

4. High-level checks via the OpenClaw plugin facade

Presence checks

# Malware only (high or above)
python openclaw_plugin.py check --type malware --severity high

# Exfil only (medium or above)
python openclaw_plugin.py check --type exfil --severity medium

# Both malware + exfil (any severity)
python openclaw_plugin.py check --type both

# List all HIGH+ findings
python openclaw_plugin.py list-high

Output (JSON):

{
  "check_type": "malware",
  "findings_total": 14,
  "matched_count": 2,
  "high_or_above": 1,
  "top_matches": [
    {
      "finding_id": "OCF-C9D2523C770B6731",
      "severity": "HIGH",
      "status": "open",
      "disposition": "unreviewed",
      "title": "OpenClaw Dangerous Exec / OpenClaw Policy Denials",
      "first_seen": "...",
      "last_seen": "..."
    }
  ]
}

Mitigation steps

python openclaw_plugin.py mitigate OCF-C9D2523C770B6731

Output:

{
  "finding_id": "OCF-C9D2523C770B6731",
  "title": "OpenClaw Dangerous Exec / OpenClaw Tool Burst",
  "severity": "HIGH",
  "status": "open",
  "disposition": "unreviewed",
  "rule_id": "RULE-109",
  "recommended_actions": [
    "Identify which agent or skill issued the dangerous execs and confirm business justification.",
    "If unauthorized, disable or restrict that skill/tool configuration in OpenClaw.",
    "Rotate any secrets used in the commands (tokens, SSH keys, API keys).",
    "Add stricter policy/approval requirements for high-risk exec operations."
  ]
}

If no curated steps exist for the detected rule, the output will include generic fallback guidance.

---

5. Daily summary via OpenClaw cron

Security note: if you enable a scheduled job, ensure it runs under a controlled account and that automated writes/triage are intended. Backup your SOC store (data/openclaw/findings/openclaw_soc.db) before enabling unattended automation.

Configure an OpenClaw cron job to run the pipeline and post a summary every morning:

• Schedule: 30 7 * * * (07:30 local)
• Action (systemEvent text):

[SECOPSAI_DAILY_SUMMARY] Run:
  cd "$HOME/secopsai" && source .venv/bin/activate &&
  python run_openclaw_live.py --skip-export &&
  python soc_store.py list
Then summarise new/HIGH findings and send a message here.

When this fires, the agent should:

1. Execute the command via exec.
2. Parse soc_store.py list output.
3. Post a short summary:

SecOpsAI: 14 findings total. New today: 2 (1 HIGH, 1 MEDIUM).

• HIGH: OCF-C9D2523C770B6731 — OpenClaw Dangerous Exec / OpenClaw Tool Burst
  Reply triage OCF-C9D2523C770B6731 to mark as true_positive+triaged.

---

6. For OpenClaw gateway operators

Running alongside an existing gateway:

• Port separation: secopsai uses no open ports by default; its Twilio bridge (if enabled) listens on a configurable local port (default 127.0.0.1:8091) behind ngrok.
• State directory: data/openclaw/ — keep it outside the gateway's writable path to avoid conflicts.
• Recommended pattern: one secopsai sidecar per gateway host. The sidecar reads from ~/.openclaw/logs/ and writes findings to its own SQLite store.
• To confirm everything is wired up:

python openclaw_plugin.py check --type both
# Should return a JSON object with findings_total > 0 after the first live run.