network-flows attestor
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 |
|
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, thefieldSetof the log,objectsread,objectsSha256,recordsRead,skipData,accountIdsandvpcIds,files[](name, sha256, log id, record count),unidentifiedFiles[](files whose names carry no flow log id: name and sha256, orunreadable: truewith no digest when the file could not be read; never parsed) andduplicateObjects[](files whose names match as one S3 object, each group withidenticalBytes; every file is read and counted, so the group explains doubled counts).addressFields: the packet address columns the rows were built from.podSnapshot:sha256of the pod list file's bytes,takenAtandtakenAtSource(operator-flag),clusterVpcIdsandclusterVpcIdsSource. 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 tosource.recordsRead.observed:coverage(600s slices of the window, how many have a record of any status, the start of each empty one),recordsWithoutVpcId,skipDataInWindow,windowEndsInsideDeliveryLagandpodSnapshotBeforeWindowEnd.blindSpots[]:{id, text}, fixed text per id, includingpod-attribution-in-policy,direction-not-classified,peer-not-classified,aws-service-traffic-not-logged,duplicate-captureandsnapshot-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.
directionis the log's value verbatim (egress,ingressor-) and part of the row's key. - A destination is an address.
serviceandtrafficPathare 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-atand--attestor-network-flows-cluster-vpc-idare 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-dstaddrandflow-directionsigns no rows andunattributed.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
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:00Zpods.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.
blindSpotssays so in every attestation. flowscounts 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-statusor 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 in 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 → · Add a new tool →
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.