pci-segment

A Go CLI for checking network policies, translating them into AWS Security Groups or Azure Network Security Groups, and generating HTML/JSON policy reports.

Policies use a Kubernetes NetworkPolicy-inspired YAML format with PCI-DSS annotations. The checks focus on segmentation concerns associated with Requirements 1.2 and 1.3; they do not establish PCI-DSS compliance or replace a segmentation assessment. Consult the PCI SSC document library for the applicable standard and assessment materials.

Capabilities and boundaries

Component	Current behavior
Policy validation	Checks API version, kind, name, port bounds, and wildcard CIDRs in CDE-labeled policies.
AWS sync	Creates named Security Groups or replaces their rules in configured VPCs.
Azure sync	Creates or updates named NSGs in configured resource groups.
Cloud validation	Checks selected wildcard rules; does not compare deployed rules with the supplied policy.
Reports	Exports policy data with three demonstration events and a label-based status.
Linux enforcement	Contains XDP filtering and audit integration, but CLI startup is blocked by lifecycle issues. Egress is not attached.
macOS enforcement	Prints generated pf rules and the command it would run; does not install them.
Audit and metrics	Library support exists; availability and coverage depend on the caller and enforcement startup.

Read before applying changes: cloud sync can replace existing rules, does not attach resources to workloads, and does not provide complete default-deny egress. Host enforcement is not a working deployment path in this checkout. See the implementation status, cloud guide, and eBPF notes.

Build and quick start

Use Go 1.24 or newer and Git. Linux builds with CGO enabled also require a C compiler, pkg-config, and libseccomp development headers; see development and packaging.

git clone https://github.com/saadshabir/pci-segment.git
cd pci-segment
go mod download
make build

# Check a valid policy.
./bin/pci-segment validate -f examples/policies/cde-isolation.yaml

# Check a second policy separately; it produces an egress warning.
./bin/pci-segment validate -f examples/policies/cde-database.yaml

# Generate demonstration reports.
./bin/pci-segment report -f examples/policies/cde-isolation.yaml -o report.html
./bin/pci-segment report -f examples/policies/cde-isolation.yaml \
  --format json -o report.json

The CLI loads one YAML policy file per invocation. It does not expand globs, scan directories, or combine multiple files. A shell-expanded -f policies/*.yaml can select only the first file and leave the others unused. For local validation of several files:

for policy in examples/policies/cde-*.yaml; do
  ./bin/pci-segment validate -f "$policy" || exit 1
done

The invalid policy is an intentional negative example: validation should exit nonzero.

Policy example

apiVersion: pci-segment/v1
kind: NetworkPolicy
metadata:
  name: cde-isolation
  annotations:
    pci-dss: "Req 1.2, Req 1.3"
spec:
  podSelector:
    matchLabels:
      pci-env: cde
  ingress:
    - from:
        - ipBlock:
            cidr: 10.0.20.0/24
      ports:
        - protocol: TCP
          port: 9090
  egress:
    - to:
        - ipBlock:
            cidr: 10.0.10.0/24
      ports:
        - protocol: TCP
          port: 443

pci-env: cde enables additional validation checks. Labels do not select real workloads, and the tool has no Kubernetes or trusted inventory integration. For portable rule translation, use explicit IPv4 ipBlock peers and uppercase TCP or UDP protocols with explicit ports. See the policy reference for fields and backend differences.

Cloud workflow

Copy and customize one of the provider configurations. Set real resource identifiers and configure credentials before running a preview:

cp examples/cloud/aws-config.yaml aws-config.local.yaml
# Edit aws-config.local.yaml for your account, region, and VPC.
./bin/pci-segment cloud-sync -f examples/policies/cde-isolation.yaml \
  --cloud-config aws-config.local.yaml --dry-run

Dry run still performs cloud reads and requires credentials. It summarizes create/update operations rather than displaying a rule-by-rule diff. The cloud guide explains applying changes, authentication, resource scope, and validation limits.

Commands

Command	Required input	Additional flags
validate	-f, --file	None
report	-f, --file	-o, --output (default pci-compliance-report.html), --format html|json
cloud-sync	-f, --file, provider config	-c, --cloud-config, --dry-run
cloud-validate	-f, --file, provider config	-c, --cloud-config, --format text|json
enforce	-f, --file	--allow-root, --compliance, --metrics-addr, --metrics-path

Global flags are --config, --log-level debug|info|warn|error, and -v, --verbose (debug logging). --file is a command flag. --compliance defaults to pci but currently does not change validation or enforcement behavior. Each command provides --help.

The configuration reference covers the global YAML file, provider files, environment variables, and their precedence. Configuration is loaded only when --config is supplied.

Understanding reports

The report command validates its input, then injects three hard-coded sample events: two blocked and one allowed. It does not read the audit log, cloud state, or a running enforcer. Its COMPLIANT status is based on the presence of a CDE-labeled policy; cde_servers counts policies rather than discovered servers, and total_servers is not populated.

Use these exports to inspect the report format and document policy intent. HTML exports label the heuristic and explain the sample-event source; JSON retains the existing field names described above. They are not evidence that traffic was blocked or that an environment meets the standard. Library callers can supply their own events through reporter.SetEvents, but the summary status remains the same heuristic.

Project structure

cmd/                    CLI commands and configuration application
pkg/policy/             YAML model, validation, and traffic matching
pkg/cloud/              AWS and Azure resource translation
pkg/enforcer/           Linux eBPF and macOS pf implementations
pkg/audit/              JSON-lines logging, rotation, and checksums
pkg/metrics/            Prometheus metrics and HTTP endpoints
pkg/reporter/           HTML and JSON exports
pkg/security/privilege/ Linux privilege, seccomp, and MAC helpers
examples/               Policy, cloud configuration, and eBPF examples

Documentation

• Policy format and validation
• Configuration and environment variables
• AWS and Azure cloud integration
• Linux enforcement lifecycle and limitations
• eBPF build and map reference
• Privilege and syscall hardening
• Audit logger behavior and integrity limits
• Development, verification, and packaging
• Implementation status and gaps

License

MIT.