Skip to main content

Illumio Core 23.2 Administration Guide

Manage Traffic Flows Using REST API

You can use the following properties to manage traffic flows using the REST API.

Note

You should ignore and not use any extra properties that are not described in this document, such as tbi, tbo, dbi, and dbo.

Property

Description

Type

Required

Possible Values

version

The version of the flow summary schema.

Integer

Yes

4

timestamp

Indicates the time (RFC3339) when the first flow in the summary was created, represented in UTC.

Format: yyyy-MM-dd'T'HH:mm:ss.SSSSSSZ

String

Yes

interval_sec

Sample duration for the flows in the summary. Default is approximately 600 seconds (10 minutes), depending on the VEN's ability to report traffic and PCE's current load.

Integer

Yes

dir

Direction of the first packet: in or out (I, O).

String

Yes

I, O

src_ip

Source IP of the flows.

String

Yes

dst_ip

Destination IP of the flows.

String

Yes

proto

Protocol number (0-255).

Integer

Yes

Minimum=0

Maximum=255

type

The ICMP message type associated with the first flow in the summary. This value exists only if protocol is ICMP (1).

Note

This information is included in blocked flows for VEN versions lower than 19.1.0. It is included in all flows for VEN version 19.1.0 and later.

Example: 3 for “Destination Unreachable.”

Integer

No

Minimum=0

Maximum=255

code

The ICMP message code (subtype) associated with the first flow in the summary. This value exists only if protocol is ICMP (1).

Note

This information is included in blocked flows for VEN versions lower than 19.1.0. It is included in all flows for VEN version 19.1.0 and later.

Example: 1 for “Destination host unreachable.”

Integer

No

Minimum=0

Maximum=255

dst_port

Destination port.

This value exists only if protocol is not TCP (6) or UDP (17).

Integer

Yes

Minimum=0

Maximum=65535

pd

Policy decision value, which indicates if the flow was allowed, potentially blocked (but allowed), blocked, or unknown.

Possible values:

  • 0 – Allowed traffic

  • 1 – Allowed traffic but will be blocked after policy enforcement

  • 2 – Blocked traffic

  • 3 - Unknown

Note

Policy decision is “unknown” in the following cases:

  • Flows uploaded using existing bulk API (/orgs/<org_id>/agents/bulk_traffic_flows).

  • Flows uploaded using Network Flow Ingest Application (/orgs/<org_id>/traffic_data).

  • Traffic reported by idle VENs and specifically those that have been reported with “s” state (snapshot).

Integer

Yes

Minimum=0

Maximum=3

count

Count of the number of flows in the flow summary.

Integer

Yes

state

Session state for the traffic flows in the flow summaries.

Possible values:

  • Active (A): Connection was still open at the time the flow summary was logged. Applies to allowed and potentially blocked flows.

  • Closed (C): (Linux only) Connection closed at the time the flow summary was logged. Applies to allowed and potentially blocked flows.

  • Timed out (T): Connection timed out at the time the flow summary was logged. Applies to allowed and potentially blocked flows. Due to a limitation of WFP, a Windows VEN will report "T" even when the connection is closed at the time the flow summary was logged.

  • Snapshot (S): Snapshot of current connections to and from the VEN, which applies only to workloads whose policy state is set to Idle. Applies to allowed and potentially blocked flows.

  • New connection (N): Dropped TCP packet contains a SYN and is associated with a new connection. Applies to blocked TCP flows. The value is empty for blocked UDP flows.

String

No

A, C, T, S, N

pn

The program name is associated with the first flow of the summary. It is supported on inbound flows for Linux and Windows VEN and on outbound flows for only Windows VEN.

Note

This information might not be available on short-lived processes, which are Linux-specific.

Currently, flows are aggregated, so this value might represent only the first process detected across all aggregated flows.

If network communication is done by an OS component (or a driver), no process is associated with it.

String

No

un

The username is associated with the first flow of the summary. It is supported on inbound flows for Linux and Windows VEN and on outbound flows for only Linux VEN.

On Windows, it can include the username of the user account that initiated the connection.

Note

This information might not be available on short-lived processes.

String

No

sn

Service name associated with the first flow in the summary. It is supported only on inbound flows on Windows VEN.

String

No

src_hostname

Hostname of the source workload that reported the flow.

String

No

src_href

HREF of the source workload that reported the flow.

String

No

src_labels

Labels applied to the source workload.

Note

The src_hostname, src_href, and src_labels values are not be included in a traffic summary if the source of the flow is not an Illumio-labeled workload. For example, Internet traffic or a managed workload without any labels applied.

Object

No

dst_hostname

Hostname of the destination workload that reported the flow.

String

No

dst_href

HREF of the destination workload that reported the flow.

String

No

dst_labels

Labels applied to the destination workload.

Note

The dst_hostname, dst_href, and dst_labels values are not be included in a traffic summary if the destination of the flow is not an Illumio-labeled workload. For example, Internet traffic or a managed workload without any labels applied.

Object

No

dst_vulns

Information about the vulnerabilities on the destination of the traffic flow with the specific port and protocol.

Note

  • Vulnerabilities are defined by Common Vulnerabilities and Exposures (CVE), with identifiers and descriptive names from the U.S. Department of Homeland Security National Cybersecurity Center.

  • The vulnerability information is sent only when the Vulnerability Maps feature is turned on via a license and the information is imported into the PCE from a Vulnerability Scanner, such as Qualys.

Object

No

fqdn

Fully qualified domain name

String

No

The following table describes the sub-properties for the dst_vulns property:

Sub-property

Description

Type

Required

count

The total number of existing vulnerabilities on the destination port and protocol.

Integer

No

max_score

The maximum of all the scores for the vulnerabilities on the destination port and protocol.

Number

No

cve_ids

The list of CVE-IDs associated with the vulnerabilities that have the maximum score. Up to 100 displayed .

Array

No