Skip to content

SecOpsAI Edge

SecOpsAI Edge is the network discovery and sensor module for the SecOpsAI platform. Edge owns authorized LAN discovery, Wi-Fi observations, worker heartbeat, and scan execution. Core owns the canonical asset graph, findings, long-term context, triage, research, and reporting workflows.

The repositories remain separate and do not share a database. They exchange a versioned secopsai.edge.bundle.v1 contract containing normalized graph nodes, graph edges, and findings. Raw Nmap output, packet captures, and raw scan logs are excluded.

Core now also exposes a protected HTTP ingestion/read boundary. See core-api.md for the local service, scoped credentials, API contract limits, and persistent deployment model.

One-Step Sync From The Edge Repo

From the SecOpsAI Edge repo:

./scripts/edge core sync --cloud --core-root "$HOME/secopsai" --output edge-bundle.json

This exports the normalized Edge bundle, saves it for audit/review, and imports it into this Core local SOC/graph store.

Supervised Automatic Sync

From the Edge repo, install the platform service that repeats the same versioned export/import safely:

./scripts/edge core sync-service install --cloud --core-root "$HOME/secopsai" --interval 300
./scripts/edge core sync-service start
./scripts/edge core sync-service status

Use logs, run-now, stop, and uninstall for recovery. The service uses launchd on macOS and a systemd user timer on Linux. It has a separate lifecycle from the scanner worker and skips overlapping runs. A staged runner avoids macOS Documents-folder privacy failures; configuration and credentials are isolated in separate owner-only JSON files, and the token is never placed in launch arguments.

Import A Bundle

secopsai edge import --bundle edge-bundle.json

Use a custom SOC/graph database:

secopsai edge import --bundle edge-bundle.json --db-path /path/to/openclaw_soc.db

Sync From Edge API

SECOPSAI_EDGE_API_URL=https://secopsai-edge-api.onrender.com \
SECOPSAI_EDGE_ACCESS_TOKEN=<workspace-core-export-token> \
secopsai edge sync

Or pass values directly:

secopsai edge sync \
  --edge-api-url https://secopsai-edge-api.onrender.com \
  --access-token <workspace-core-export-token>

Create this expiring, revocable token from the Edge dashboard Settings page. It grants only core:export for the selected workspace. The legacy admin-token environment variable and CLI alias remain temporarily supported for existing single-workspace installations, but new services should not use them.

To push the normalized bundle into a hosted Core API, keep the two credentials separate and prefer environment variables so they do not appear in process arguments:

SECOPSAI_EDGE_API_URL=https://secopsai-edge-api.onrender.com \
SECOPSAI_EDGE_ACCESS_TOKEN=<workspace-core-export-token> \
SECOPSAI_CORE_API_URL=https://secopsai-core-api.onrender.com \
SECOPSAI_CORE_INGEST_TOKEN=<core-ingest-token> \
secopsai edge sync --remote-only

Use --remote-only when the sensor host should not maintain a second local Core SQLite mirror. Omit it to update both the local Core store and hosted Core in one idempotent operation. The command returns only import counts, status, schema, source identity, and request ID; it never prints either credential or the bundle body.

Inspect The Graph

secopsai graph assets
secopsai graph show 192.168.1.50
secopsai graph changes

Inspect Edge-to-Core freshness without running another sync:

secopsai edge status

The status output includes the Edge source identity, contract version, bundle timestamp, local sync timestamp, and cursor. It contains no raw scanner data.

Review Edge Findings

secopsai triage list --source secopsai_edge
secopsai triage investigate EDGE-...

Core stores Edge findings with stable EDGE-... identifiers and preserves analyst triage state on re-sync. The Edge source identity is scoped to its organization and remains stable when the Edge API version changes, preventing routine upgrades from creating a new sync cursor.

Approval-Gated Edge Scan Requests

OpenClaw can request a scan without being allowed to run Nmap or mutate the Edge service directly. The request creates a Core session and a pending approval:

secopsai_edge_request_scan targetCidr=192.168.1.0/24 includeWifi=false
secopsai_session_show sessionId=SES-...
secopsai_session_resolve_approval sessionId=SES-... approvalId=APR-... decision=approved apply=true

The plugin passes its configured edgePath to Core. When the approval is applied, Core invokes only <edgePath>/scripts/edge queue <cidr> --cloud with structured arguments. Edge validates the RFC1918 /24 boundary again, uses its local scoped cloud credentials, and creates a queued job for the local worker. The worker remains the only component that executes discovery.

Core stores only the normalized target, Wi-Fi flag, approval ID, and queue status in the session. It does not store the helper stdout, raw Nmap output, packet data, or sensor/admin credentials. Rejected approvals do not queue a job. Operators must explicitly allow the optional write tools in OpenClaw.

The same approval boundary covers report generation and worker lifecycle actions:

secopsai_edge_request_report
secopsai_edge_request_worker_action action=start
secopsai_session_resolve_approval sessionId=SES-... approvalId=APR-... decision=approved apply=true

Report generation invokes the existing Edge report --cloud helper and keeps the generated report in Edge's authenticated report store. Worker start/stop invokes only the allowlisted worker start or worker stop action. Neither operation returns helper output to Core or exposes a credential to OpenClaw.

Ownership Boundary

Surface Owner
LAN and Wi-Fi collection Edge sensor
Scan jobs, schedules, and worker health Edge API
Raw scan minimization Edge agent
Canonical findings and analyst disposition Core
Asset graph and long-term change context Core
Unified asset/finding operator workspace SecOpsAI dashboard
Scan, schedule, and sensor administration Edge dashboard
Local automation and approval-gated actions OpenClaw plugin

The canonical SecOpsAI dashboard now consumes Core graph assets, graph changes, and Edge-origin findings, with optional server-side enrichment from the Edge API for live sensor operations. The Edge dashboard remains the administration surface for scans, schedules, and sensor recovery. Edge credentials are held by the helper service and are never exposed to the browser.