wirecrab 0.1.0

Agent-first CLI network analysis platform
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# wirecrab

Agent-first CLI network analysis platform.

## Build

```bash
cargo build
```

## Key Commands

Create/list/delete sessions:

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

Start/stop live capture:

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

Run SQL queries:

```bash
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:

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

Inject packets from spec:

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

Run probe script:

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

Inspect schema and environment:

```bash
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:

```bash
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)

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

You can use `payload_base64` instead of `payload_hex`.

## Probe Script (YAML)

```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`.