CycloneDX SBOM indexer

Cyclops is a tool to ingest, index and search through CycloneDX SBOMs. Point it to a directory containing CycloneDX files (and optionally an S3 bucket path) - it will index the files and makes them searchable through a simple command line interface.

Database engine is SQLite, for two reasons:

1. No need to set up external DB for what should be a simple, local only tool
2. The driver used exports a database/sql interface, so it should be reasonably low effort to port the tool to use a dedicated, separate database instance. Should the need arise.

Cyclops is licensed under AGPL.

Download: cyclops.tar.xz (~40kB)

Git: git clone https://bostik.iki.fi/src/cyclops.git

Examples

List ingested SBOM types

cyclops -J

List detected packaging ecosystems, number of packages

cyclops -E

Ingest SBOMs

cyclops -d /path/to/somewhere/with/sboms/

Download SBOMs from S3 in addition to ingesting them

cyclops \
    -d /path/to/somewhere/with/sboms/ \  # becomes download path 
    --s3-get \
    --s3-bucket <BUCKET NAME> \
    --s3-prefix <OBJECT PATH PREFIX> \
    [--s3-max-days <MAX OBJECT AGE>] \
    [--s3-max-dl-batch <PARALLEL DOWNLOAD BATCH SIZE>]

List known packages, their ecosystems, how many found

cyclops -P

List known packages, how many found for a single ecosystem

cyclops -P -p <ECOSYSTEM>

List indexed SBOMs

cyclops -L

List indexed SBOMs for a specific type only

cyclops -L -j <SBOM TYPE>

Search for dependencies by a partial detection path match

cyclops -S <PATH MATCH>

Search for packages whose names include 'foo'

cyclops -m foo

Search for any number of known package names

cyclops -n pkg1 pkg2 pkg3 [...] pkgN

Special case for eg. Sha1-Hulud investigation ("do I have any of these infected packages anywhere in my stack?"):

cut -d ',' -f1 /path/to/downloaded/sha1-hulud.csv \
    | xargs cyclops -n

Various options can be usually combined to list or search through dependencies only for a given SBOM type and/or a specific packaging ecosystem.

Why?

I have had a persistent problem at $work. We generate and publish SBOMs but the only external use I've seen for them is to feed them to context-free vulnerability "scanner" software.

Cyclops began as a personal tool to make searching for detection paths and dependency bloat easier. The data in SBOMs, especially in aggregate, is far more valuable as a supply chain analytics material and I wanted to see if I could make this use case more accessible.

The tool has been written entirely outside of work, though. I had a problem, some spare time and needed a creative outlet.

Why AGPL?

I wanted to explicitly discourage anyone from picking up a tool I wrote for terminal investigations and turning it into a hosted SaaS.

NOTE: the DB schema file is intentionally licensed under CC0; I wanted it to be clear that any data you have stored in Cyclops's database is always yours. If you want to interact with it for eg. analytics purposes, you are free to write tools of your choice to generate reports from data held in the SQLite file. As long as these tools do not use the code from the rest of Cyclops, they will remain unaffected by the project's chosen license.

Miscellania

Cyclops was first presented at DC4420.

The name is a homage to CycloneDX project and a play on the far too common myopic practice of using SBOMs as a fancy input to whatever vulnerability scanner[TM] happens to be available.

Supports generating a Zsh autocompletion script with cyclops completion.