Skip to main content
View Markdown ↗

Copy this page

Select and copy the Markdown below, then paste it into your LLM.

On this page

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.

Namenetwork-flows
Predicate typehttps://aflock.ai/attestations/network-flows/v0.2
Lifecyclepostproduct
Default binary?No
Categoryruntime-event (primary)
Recommended traceoff — 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

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

FlagDefaultWhat 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-window1hHow much traffic the attestation covers.
--attestor-network-flows-window-endnow minus delivery-lagEnd of the window, RFC 3339.
--attestor-network-flows-delivery-lag10mHow 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 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.