Trivy Configuration#
Prerequisites#
Install Trivy by following the official Trivy installation guide. Populate the graph with the image or filesystem snapshot resources that you want to scan before running the Trivy module. For AWS ECR:
cartography --selected-modules aws --aws-requested-syncs ecr
Trivy scans ECR repository images, while Cartography attaches findings to
their underlying AWSECRImage nodes.
For a source filesystem snapshot, check out the exact commit while retaining the repository’s Git metadata, then run:
trivy fs --format json --scanners vuln --list-all-pkgs /path/to/repository
Cartography uses Metadata.RepoURL and the full SHA in Metadata.Commit to
match the report to every FilesystemSnapshot for that repository revision.
For EC2 root filesystems, sync the instances before producing or importing VM reports so their filesystem targets exist in the graph. Use the same AWS account and region as the scan, for example:
cartography --selected-modules aws --aws-requested-syncs ec2:instance \
--aws-regions us-east-1
EC2 discovery creates targets for eligible running Linux instances with an EBS root volume. See VM Reports for the scan and ingestion commands.
Required Permissions#
The AWS credentials used to generate reports need the following permissions. The VM row includes root-volume lookup and temporary snapshot creation/cleanup in addition to Trivy’s snapshot reads.
Cartography node label |
Cloud permissions required to scan with Trivy |
|---|---|
|
|
|
|
For customer-managed KMS keys, the key policy must also allow the scanning
principal to use the key. See the AWS EBS direct API permissions
guide
for policy examples, including restricting grants with
kms:GrantIsForAWSResource.
Cartography’s AWS module needs no new permissions to discover filesystem
targets: it uses the DescribeInstances data it already fetches. The snapshot
creation, deletion, EBS direct API, and KMS permissions above belong to the scan
producer; importing local JSON reports does not require them.
For reports in S3, the role running Cartography needs s3:ListBucket on the
configured bucket and s3:GetObject on objects under the configured prefix.
Configure Cartography#
Set --trivy-source to a local path, s3://bucket/prefix,
gs://bucket/prefix, or azblob://account/container/prefix. Cartography
ingests every .json file under the source.
Run Cartography#
For reports in an object store:
cartography --selected-modules trivy --trivy-source s3://my-bucket/trivy-scans/
For local reports:
cartography --selected-modules trivy --trivy-source /path/to/trivy-results
Input Artifacts#
Generate Input Artifacts#
Scan images or checked-out repositories with Trivy and put the JSON results in a local directory or supported object store. Cartography requires these Trivy arguments:
--format json: Cartography only accepts JSON, including the usefulfixed_versionfield.--security-checks vuln: Scan for vulnerabilities.
Optional Trivy arguments include:
--ignore-unfixed: Ignore vulnerabilities without a fixed version.--list-all-pkgs: Include all packages in the image, not only packages with vulnerabilities. Cartography attaches all included packages to the canonicalImagenode.--timeout 15m: Allow additional time for larger images, such as Java images.--vuln-type os: Scan only operating system packages. Remove this option when you also want visibility into application library vulnerabilities.Custom OPA policies can filter results before Cartography ingests the report.
Input Format#
JSON files can use any naming convention. Cartography determines which scan target a report belongs to from the scan content, not the filename. You can use an object prefix to organize cloud results. For example:
s3://my-bucket/trivy-scans/123456789012.dkr.ecr.us-east-1.amazonaws.com/test-app:v1.2.3.jsons3://my-bucket/trivy-scans/scan-12345.json
Cartography supports scans identified by tag URIs such as repo:tag and digest
URIs such as repo@sha256:abc123.... Digest-qualified URIs support
multi-architecture images where each platform has its own digest. Cartography
matches scans to canonical images using the digest in Metadata.RepoDigests.
Filesystem reports must use ArtifactType filesystem or repository and
include Metadata.RepoURL plus a 40-character Metadata.Commit. Reports without
an exact graph match are skipped.
VM Reports#
Report identity#
VM reports use ArtifactType: "vm". Before ingestion, the scan producer must
add Metadata.FilesystemSnapshotId containing the stable graph target ID:
{
"ArtifactType": "vm",
"ArtifactName": "ebs:snap-0123456789abcdef0",
"Metadata": {
"FilesystemSnapshotId": "aws:ec2:i-0123456789abcdef0:rootfs"
}
}
This example shows the identity fields; retain the report’s other metadata and
results. Trivy does not add FilesystemSnapshotId itself. The target must already
exist as a FilesystemSnapshot with _ont_kind="rootfs", connected by
(ComputeInstance)-[:SCANNED_AS]->(FilesystemSnapshot). EC2 discovery creates
these targets before report ingestion.
Each EC2 target stores the root EBS volume_id and links to that volume through
(FilesystemSnapshot)-[:SNAPSHOT_OF]->(AWSEBSVolume:BlockStorage). If the root
volume is replaced, the next EC2 sync updates this property and relationship
while keeping the target ID stable.
Cartography uses this stable ID because the temporary EBS snapshot in
ArtifactName can change on every scan. Missing, invalid, or unmatched IDs are
skipped with a warning. A successful report with zero vulnerabilities clears
that target’s old findings.
Cleanup is scoped by report type. A batch with VM reports removes stale results from every scanned VM target, including targets without a report in the batch, so supply all current VM reports together. Image and source repository results are kept when the batch has no reports of that type, and the same applies to VM results when the batch has no VM reports. Supply one report per target: multiple reports for the same target in one batch are merged. Read or parse failures, or a batch with no matching reports, skip cleanup.
Scan an EC2 root filesystem#
First complete the EC2 sync in Prerequisites. Install the AWS
CLI and jq alongside Trivy, and configure AWS credentials for the instance’s
account. Choose an eligible instance with a supported root filesystem, as
described in the limits below.
Run the following in Bash, replacing instance_id and scan_region. It finds
the root volume, creates a tagged temporary EBS snapshot, waits for it to be
ready, scans it, and stamps the stable target ID while preserving all other
report fields. The subshell’s exit trap deletes the snapshot on success or
failure, including when Trivy fails. If deletion fails, it prints the snapshot
ID for manual cleanup and exits with an error.
(
set -euo pipefail
instance_id="i-0123456789abcdef0"
scan_region="us-east-1"
report_dir="./trivy-vm-reports"
scan_work_dir="$(mktemp -d)"
snapshot_id=""
cleanup() {
scan_status=$?
if [[ -n "$snapshot_id" ]]; then
if ! aws ec2 delete-snapshot --region "$scan_region" \
--snapshot-id "$snapshot_id"; then
echo "Delete snapshot $snapshot_id in $scan_region manually." >&2
scan_status=1
fi
fi
rm -rf "$scan_work_dir"
exit "$scan_status"
}
trap cleanup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
instance_json="$(aws ec2 describe-instances --region "$scan_region" \
--instance-ids "$instance_id" --output json)"
volume_id="$(jq -er '
.Reservations[0].Instances[0]
| .RootDeviceName as $root
| .BlockDeviceMappings[]
| select(.DeviceName == $root)
| .Ebs.VolumeId // empty
' <<< "$instance_json")"
snapshot_id="$(aws ec2 create-snapshot --region "$scan_region" \
--volume-id "$volume_id" \
--description "Cartography rootfs scan for $instance_id" \
--tag-specifications 'ResourceType=snapshot,Tags=[{Key=cartography:scan,Value=true}]' \
--query SnapshotId --output text)"
aws ec2 wait snapshot-completed --region "$scan_region" \
--snapshot-ids "$snapshot_id"
trivy vm --aws-region "$scan_region" --format json --scanners vuln \
--list-all-pkgs --timeout 30m --output "$scan_work_dir/raw.json" \
"ebs:$snapshot_id"
jq --arg id "aws:ec2:$instance_id:rootfs" \
'.Metadata.FilesystemSnapshotId = $id' \
"$scan_work_dir/raw.json" > "$scan_work_dir/report.json"
mkdir -p "$report_dir"
mv "$scan_work_dir/report.json" "$report_dir/$instance_id.json"
)
Only the completed, stamped report is placed in trivy-vm-reports; the raw
report stays outside the ingestion directory. After the script succeeds, import
the report into the same Neo4j database used for EC2 discovery, adding your
usual Neo4j connection options to both Cartography commands as needed:
cartography --selected-modules trivy --trivy-source ./trivy-vm-reports/
The temporary EBS snapshot is already deleted at this point. Cartography needs only the saved JSON and the stable filesystem target in the graph.
Limits#
Trivy’s VM mode is experimental and may change without backwards compatibility. Its direct disk reader supports ext2, ext3, ext4, and XFS; LVM and ZFS are unsupported. See Trivy’s VM scanning documentation.
This workflow scans the instance’s root EBS volume only, not attached data volumes. EC2 discovery excludes Windows, macOS, stopped instances, and instances identified by Kubernetes tags. It cannot detect unsupported filesystems such as LVM or ZFS from EC2 metadata alone.
Kubernetes exclusion relies on the
eks:cluster-name,alpha.eksctl.io/cluster-name, orkubernetes.io/cluster/tags. Self-managed Kubernetes nodes without these tags and ECS container instances can still receive targets. Scanning those hosts alongside their container images can produce overlapping package and vulnerability results.Encrypted volumes require access to their KMS key. A missing permission is a scan failure, not a report with zero vulnerabilities; do not import an empty replacement report after a failed scan.
Advanced Configuration#
Deprecated local and S3 report-source flags remain accepted until Cartography
v1.0.0 and emit warnings when used. New configurations should use
--trivy-source.