wirecrab

Agent-first CLI network analysis platform.

Build

cargo build

Key Commands

Create/list/delete sessions:

wirecrab sessions create
wirecrab sessions list
wirecrab sessions delete --id <session-id>

Start/stop live capture:

wirecrab capture start --iface en0 --session <session-id>
wirecrab capture stop --session <session-id>

Run SQL queries:

wirecrab query --session <session-id> --sql "SELECT ts_sec, src_ip, dst_ip, l4_proto FROM packets LIMIT 25" --format json

Export filtered packets to PCAP:

wirecrab export pcap --session <session-id> --out /tmp/out.pcap --where "l4_proto = 'tcp'"

Inject packets from spec:

wirecrab inject --session <session-id> --iface en0 --spec inject.yaml

Run probe script:

wirecrab probe run --session <session-id> --script probe.yaml

Inspect schema and environment:

wirecrab schema --session <session-id>
wirecrab doctor

SQL Contract v1

Wirecrab is decision-neutral: it exposes facts for agents via SQL.

Canonical entities:

• v1_sessions
• v1_packets
• v1_flows
• v1_dns_queries
• v1_http_requests
• v1_service_discovery
• v1_stun_events
• v1_endpoint_ownership
• v1_snapshots
• v1_snapshot_protocol_mix
• v1_snapshot_top_endpoints
• v1_snapshot_top_flows
• v1_snapshot_discovery
• v1_snapshot_dns_top_qnames
• v1_snapshot_protocol_diff
• v1_snapshot_endpoint_diff
• v1_snapshot_flow_diff

SQL functions:

• v1_snapshot_create(label) -> snapshot_id
• v1_snapshot_create(label, start_sec, end_sec) -> snapshot_id
• v1_snapshot_delete(snapshot_id) -> rows_deleted
• v1_enrich_ip(ip) -> 1 if updated/inserted, 0 if cache still fresh

Examples:

wirecrab query --session <session-id> --sql \
"SELECT * FROM v1_flows ORDER BY byte_count DESC LIMIT 20" --format json

wirecrab query --session <session-id> --sql \
"SELECT v1_snapshot_create('baseline', NULL, NULL) AS snapshot_id" --format json

wirecrab query --session <session-id> --sql \
"SELECT v1_enrich_ip('2607:6bc0::10')" --format json

Inject Spec (YAML)

iface: en0
payload_hex: "ffffffffffff0011223344550800450000280001000040060000c0a80101c0a8010204d2005000000000000000005002200000000000"
count: 1
interval_ms: 100

You can use payload_base64 instead of payload_hex.

Probe Script (YAML)

iface: en0
steps:
  - type: inject
    payload_hex: "ffffffffffff0011223344550800450000280001000040060000c0a80101c0a8010204d2005000000000000000005002200000000000"
    count: 1
  - type: sleep
    ms: 500
  - type: query
    sql: "SELECT count(*) AS n FROM packets"

Notes

• Live capture and packet injection require OS-level capture permissions.
• Session data is stored in ~/.wirecrab/sessions/<session-id>/session.db.
• Query output formats: json, jsonl, csv, human.