# network-flows attestor

Source: https://www.testifysec.com/docs/cilock/attestors/network-flows/

The cilock network-flows attestor reads a cloud flow log and signs its raw rows, with the digest of the pod snapshot supplied. It never joins a pod; that is policy's, and what it cannot classify is named, never guessed.

Reads an AWS VPC flow log (plain-text delivery) and signs raw rows: what each capturing interface (instance and interface) logged for one packet source, packet destination, destination port and protocol, with the log's own direction, service and traffic path, and the flows, packets, bytes and rejected count in the window. It also signs the sha256 of the pod list the operator supplied, and never reads it. Which pod a row belongs to is decided in policy, where the cluster is known. Slice 1 signs observations only and no verdict: there is no `status`, `ok` or `complete` field. What it cannot classify is counted in `unattributed` or named in `blindSpots`. The rule is in `docs/design/planned/network-flows-fail-closed.md`.

 

| Name | `network-flows` |
| --- | --- |
| Predicate type | `https://aflock.ai/attestations/network-flows/v0.2` |
| Lifecycle | `postproduct` |
| Default binary? | No |
| Category | runtime-event (primary) |
| Recommended trace | off — no syscall tracing needed |
| Auto-attaches when | - preenv\_set: CILOCK\_NETWORK\_FLOWS |

The facts in this box are generated from the CI/lock binary's own catalog (`cilock tools list`). Do not hand-edit — run `npm run gen:catalog`.

 

## What it captures

 

Predicate `https://aflock.ai/attestations/network-flows/v0.2`:

 

- `window`: `start`, `end` (a record counts when it started inside) and the delivery lag the window ends before now.
 - `source`: `provider` (`aws-vpc-flow-logs`), `logId`, `destination`, the `fieldSet` of the log, `objects` read, `objectsSha256`, `recordsRead`, `skipData`, `accountIds` and `vpcIds`, `files[]` (name, sha256, log id, record count), `unidentifiedFiles[]` (files whose names carry no flow log id: name and sha256, or `unreadable: true` with no digest when the file could not be read; never parsed) and `duplicateObjects[]` (files whose names match as one S3 object, each group with `identicalBytes`; every file is read and counted, so the group explains doubled counts).
 - `addressFields`: the packet address columns the rows were built from.
 - `podSnapshot`: `sha256` of the pod list file's bytes, `takenAt` and `takenAtSource` (`operator-flag`), `clusterVpcIds` and `clusterVpcIdsSource`. The file is hashed and never parsed.
 - `rows[]`: `instanceId`, `interfaceId`, `direction`, `src`, `dst`, `port`, `protocol`, `service`, `trafficPath`, `flows`, `packets`, `bytes`, `rejected`, `firstSeen`, `lastSeen`. A row never merges across instances, interfaces or directions, and the list is never trimmed: the 200001st distinct row is an error.
 - `unattributed`: every record read lands in exactly one bucket (`counted`, `outsideWindow`, `skipData`, `noData`, `noPacketAddresses`) and the buckets sum to `source.recordsRead`.
 - `observed`: `coverage` (600s slices of the window, how many have a record of any status, the start of each empty one), `recordsWithoutVpcId`, `skipDataInWindow`, `windowEndsInsideDeliveryLag` and `podSnapshotBeforeWindowEnd`.
 - `blindSpots[]`: `{id, text}`, fixed text per id, including `pod-attribution-in-policy`, `direction-not-classified`, `peer-not-classified`, `aws-service-traffic-not-logged`, `duplicate-capture` and `snapshot-unread`.

 

Subject: `network-flows://<provider>/<log id>/<window start>/<window end>`, digest = sha256 of the JSON of `rows` exactly as the predicate carries it. A window boundary with a fraction of a second is refused; the default end is cut to the second.

 

## Why this shape

 

Under the AWS VPC CNI, a flow log's `srcaddr` and `dstaddr` are the logging interface's addresses and name no pod; the pod is `pkt-srcaddr` on egress. An earlier shape joined those addresses to a pod list inside the attestor, and eighteen review rounds ended on a case no input can settle: a pod whose node is gone but still reads `Running`, whose released address a new instance acquired. The attestor now signs the instance and interface that logged each row and the digest of the pod list, and the policy that knows the cluster does the join, with its own rules for readiness time, departed nodes and shared addresses.

 

- A row does not say who opened a connection. `direction` is the log's value verbatim (`egress`, `ingress` or `-`) and part of the row's key.
 - A destination is an address. `service` and `trafficPath` are the log's own values and part of the key, so a policy can tell traffic path 7 (a gateway endpoint) from 8 (an internet gateway).
 - The pod list carries no read time and names no network, so `--attestor-network-flows-pods-taken-at` and `--attestor-network-flows-cluster-vpc-id` are required and recorded as the operator's assertions.
 - A flow log file whose name carries no flow log id is listed and never read. A log without `pkt-srcaddr`, `pkt-dstaddr` and `flow-direction` signs no rows and `unattributed.noPacketAddresses`.

 

Nothing in the predicate says the window is complete. A policy decides from `observed.coverage`, `source.duplicateObjects`, `observed.skipDataInWindow`, `unattributed` and the blind spots.

 

## Validated invocation

 

```sh
cilock attest --step network-flows -a network-flows \
  --attestor-network-flows-flow-log-dir ./flow-logs \
  --attestor-network-flows-flow-log-id fl-0123456789abcdef0 \
  --attestor-network-flows-pods-file pods.json \
  --attestor-network-flows-pods-taken-at 2026-11-15T15:01:00Z \
  --attestor-network-flows-cluster-vpc-id vpc-0123456789abcdef0 \
  --attestor-network-flows-window 1h \
  --attestor-network-flows-window-end 2026-11-15T15:00:00Z
```

 

`pods.json` is `kubectl get pods --all-namespaces -o json`, read at the end of the window, and is the list the policy joins against. Relative paths resolve against the attestation working directory. This version reads files; reading S3 and the cluster directly follows.

 

## Flags

 

| Flag | Default | What it does |
| --- | --- | --- |
| `--attestor-network-flows-flow-log-dir` | (required) | Directory of downloaded flow log files (`.log`, `.log.gz`, plain-text delivery). |
| `--attestor-network-flows-flow-log-id` | (only one allowed) | Flow log id (`fl-...`) to read. Required when the directory holds more than one flow log. |
| `--attestor-network-flows-pods-file` | (required) | The pod list the policy will join against. Hashed, never read. |
| `--attestor-network-flows-pods-taken-at` | (required) | When the pod list was read, RFC 3339. A file time is not used. |
| `--attestor-network-flows-cluster-vpc-id` | (required) | The one VPC id the cluster runs in (`podSnapshot.clusterVpcIds`, `clusterVpcIdsSource: operator-flag`). Every record of the log that carries a vpc-id must carry this one or the run fails; an OK record with none fails too; NODATA and SKIPDATA records with none are counted in `observed.recordsWithoutVpcId`. |
| `--attestor-network-flows-window` | `1h` | How much traffic the attestation covers. |
| `--attestor-network-flows-window-end` | now minus delivery-lag | End of the window, RFC 3339. |
| `--attestor-network-flows-delivery-lag` | `10m` | How long before now the window ends, so the log has finished writing. |

 

## Needs from the flow log

 

Required fields: `srcaddr dstaddr srcport dstport protocol packets bytes start end action log-status vpc-id interface-id`. `interface-id` is part of every row's identity, so an OK record with `-` there is refused. For rows: `pkt-srcaddr pkt-dstaddr flow-direction`. Preferred: `instance-id` (the policy join needs it) and `traffic-path`. Optional: `pkt-dst-aws-service`. Parquet delivery is refused with an error.

 

## How a verifier consumes this

 

Policy reads `rows[]` and joins them to pods using the snapshot whose digest is `podSnapshot.sha256` and the cluster's own node and instance data. It owns the completeness verdict: for example require `observed.coverage.emptySlices` empty, `source.duplicateObjects` empty, `observed.skipDataInWindow` zero and the blind spots acceptable. Absence of a row does not prove no connection was opened.

 

## Gotchas

 

- Not seen by design: traffic between pods on one node (never leaves the host), traffic to the Amazon DNS resolver and the instance metadata service, and traffic source-NATed before the capture point. `blindSpots` says so in every attestation.
 - `flows` counts flow log records, not connections. Rows from two interfaces that logged one packet are two rows.
 - Every column of every record is checked against a closed grammar whatever its status (a truncated `action`, `log-status` or direction, an address or number that does not parse, a record of a VPC other than the cluster's, a file whose last line has no newline, a header field AWS does not define or repeats): a violation is an error, never a default.
 - A failure to read (no cluster VPC, no file names a flow log id, no files, a pod snapshot that is missing or not a regular file, no snapshot time, a window whose start is not before its end) is an error and signs nothing. A window with no record signs the empty coverage.

 

## Later slices

 

The policy-side join, connection direction, peer classification, S3 and live cluster reads. See `docs/design/planned/network-flows-fail-closed.md`.

 

## See also

 

`docs/design/planned/network-flows-fail-closed.md` in the judge repository; the `k8smanifest` attestor for cluster state.

 

---

**This page is generated from the CI/lock tool catalog.** Don't edit it here — the source is [`attestation/detection/docs/network-flows.doc.md`](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/network-flows.doc.md) in [aflock-ai/rookery](https://github.com/aflock-ai/rookery). The same catalog powers `cilock tools show network-flows` in the CLI, so a single edit keeps the terminal and the website in sync.

[Edit this page →](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/network-flows.doc.md) ·  [Add a new tool →](https://github.com/aflock-ai/rookery/new/main/attestation/detection/docs)

When you open the pull request: if you are an **AI agent**, add the `ai-agent` label. If you are a **human**, add the `human` label.

Reference generated from the product documentation. Match commands and support details to your installed release.
