childflow 0.6.0

A per-command-tree network sandbox for Linux
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
133
134
135
136
137

childflow Flow Log Schema
===

This document describes the current structured JSON Lines schema emitted by `childflow --flow-log`.

## Status

- current `schema_version`: `1`
- current backend support: `rootless-internal`
- current output format: one JSON object per line

## Common Fields

Every event currently includes these fields:

| Field | Type | Notes |
| --- | --- | --- |
| `schema_version` | integer | Current value is `1` |
| `ts_ms` | integer | Unix epoch milliseconds |
| `event` | string | Event name |

## Event Types

### `dns_query`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `event` | string | Yes | Always `dns_query` |
| `protocol` | string | Yes | Always `udp` |
| `server` | string | Yes | Socket string such as `1.1.1.1:53` |
| `server_ip` | string | Yes | IP-only server field |
| `server_port` | integer | Yes | Current value is `53` |
| `qtype` | string | Yes | Current values are `A`, `AAAA`, `other`, or `unknown` |

Example:

```json
{"schema_version":1,"ts_ms":1760000000000,"event":"dns_query","protocol":"udp","server":"1.1.1.1:53","server_ip":"1.1.1.1","server_port":53,"qtype":"A"}
```

### `dns_answer`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `event` | string | Yes | Always `dns_answer` |
| `protocol` | string | Yes | Always `udp` |
| `server` | string | Yes | Socket string such as `1.1.1.1:53` |
| `server_ip` | string | Yes | IP-only server field |
| `server_port` | integer | Yes | Current value is `53` |
| `qtype` | string | Yes | Mirrors the paired query classification |
| `mode` | string | Yes | Current values are `relayed` or `synthetic_empty` |
| `bytes` | integer | Yes | Response payload length |

Example:

```json
{"schema_version":1,"ts_ms":1760000000001,"event":"dns_answer","protocol":"udp","server":"1.1.1.1:53","server_ip":"1.1.1.1","server_port":53,"qtype":"A","mode":"relayed","bytes":128}
```

### `connect_attempt`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `event` | string | Yes | Always `connect_attempt` |
| `protocol` | string | Yes | Always `tcp` |
| `remote_addr` | string | Yes | Socket string such as `93.184.216.34:443` |
| `remote_ip` | string | Yes | IP-only remote field |
| `remote_port` | integer | Yes | Remote port |
| `via_proxy` | boolean | Yes | Whether the connection uses the configured upstream proxy path |

Example:

```json
{"schema_version":1,"ts_ms":1760000000002,"event":"connect_attempt","protocol":"tcp","remote_addr":"93.184.216.34:443","remote_ip":"93.184.216.34","remote_port":443,"via_proxy":false}
```

### `connect_result`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `event` | string | Yes | Always `connect_result` |
| `protocol` | string | Yes | Always `tcp` |
| `remote_addr` | string | Yes | Socket string such as `93.184.216.34:443` |
| `remote_ip` | string | Yes | IP-only remote field |
| `remote_port` | integer | Yes | Remote port |
| `via_proxy` | boolean | Yes | Whether the attempted connection used the proxy path |
| `status` | string | Yes | Current values are `ok` or `error` |
| `error` | string or null | Yes | Error detail when `status` is `error`, otherwise `null` |

Example:

```json
{"schema_version":1,"ts_ms":1760000000003,"event":"connect_result","protocol":"tcp","remote_addr":"93.184.216.34:443","remote_ip":"93.184.216.34","remote_port":443,"via_proxy":false,"status":"ok","error":null}
```

### `policy_violation`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `event` | string | Yes | Always `policy_violation` |
| `protocol` | string | Yes | Current values include `tcp`, `udp`, `dns`, `icmpv4`, `icmpv6` |
| `remote` | string | Yes | Human-readable remote target |
| `remote_ip` | string or null | Yes | Present when the violation has a concrete remote IP |
| `remote_port` | integer or null | Yes | Present when the violation has a concrete port |
| `action` | string | Yes | Current value is `deny` |
| `reason_code` | string | Yes | Current values include `offline`, `metadata`, `private`, `deny_cidr`, `default_deny`, `proxy_only` |
| `control` | string | Yes | Current values include `--offline`, `--block-metadata`, `--block-private`, `--deny-cidr`, `--default-policy`, `--proxy-only` |
| `matched_cidr` | string or null | Yes | Set for CIDR-based deny rules |
| `reason` | string | Yes | Human-readable explanation |

Example:

```json
{"schema_version":1,"ts_ms":1760000000004,"event":"policy_violation","protocol":"tcp","remote":"10.0.0.1:443","remote_ip":"10.0.0.1","remote_port":443,"action":"deny","reason_code":"deny_cidr","control":"--deny-cidr","matched_cidr":"10.0.0.0/8","reason":"blocked by `--deny-cidr 10.0.0.0/8`"}
```

### `flow_end`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `event` | string | Yes | Always `flow_end` |
| `protocol` | string | Yes | Current value is `tcp` |
| `remote_addr` | string | Yes | Socket string such as `93.184.216.34:443` |
| `remote_ip` | string | Yes | IP-only remote field |
| `remote_port` | integer | Yes | Remote port |

Example:

```json
{"schema_version":1,"ts_ms":1760000000005,"event":"flow_end","protocol":"tcp","remote_addr":"93.184.216.34:443","remote_ip":"93.184.216.34","remote_port":443}
```

## Compatibility Notes

- Additive fields within the same `schema_version` should be considered possible.
- Changes that would remove fields, rename fields, or change value meanings should increment `schema_version`.
- Consumers should ignore unknown fields when possible.