Ocular Glossary

Since Ocular is built upon Kubernetes, users should also reference the kubernetes glossary as many terms will also be used from there.

Target

A static software asset to be scanned, “static” meaning that it can be represented on a file system. Some examples are git repository, container images, file archives, software packages, etc.

Container Definition

This is static definition of a container to execute. It includes the container image URI, image pull policy, environment variables, secrets, command and arguments. It is a simplified version of a kubernetes container.

Downloader

A container definition that runs during a pipeline and should download the target to be scanned. This container will be fed the target identifier and optional version, and expected to write the target to disk. This will execute before the scanners are run.

Crawler

A container definition that will run during a search and should enumerate targets to be scanned. The container will be given an authenticated token that has the ability to trigger pipelines and should be used to start scans for each target it finds. Crawlers support named parameters that are passed by the user as key-value pairs when executing a search and given to the container via environment variables.

Uploader

A container definition that will as the last stage of a pipeline (after the scanners) and should upload results to a 3rd party. The container will be given a list of output files via the command-line args to process/upload. Uploaders support named parameters that are passed by the user as key-value pairs in a profile and given to the container via environment variables.

Profile

A profile is a definition made of 3 parts:

  1. A list of container definitions of the scanner to run
  2. A list of artifacts that will be output from all the scanners
  3. The names of the uploaders to run after the scanners complete

A profile is given during the creation of a pipeline and describes what to scan with and what to do with results. Profiles allow for users to easy define different types of scans for Ocular to run and allow for easy switching between them.

Pipeline

A pipeline is the execution of a downloader and a profile for a scan target. To trigger a pipeline a user will provide an identifier and optional version for a target, the name of the downloader to use to download the target, and the name of the profile to execute once downloaded. A pipeline first executes the downloader and once successfully complete, runs all scanners from the profile in parallel. Once all scanners have completed, all specified uploaders will be run in parallel.

A Search is the execution of a crawler. Searches can be configured to run on a cron-schedule or triggered ad-hoc. When a search is scheduled or triggered, the user will can supply key-value pairs to be passed to the crawler as environment variables. The crawler container will have an authenticated token mounted that allows for starting pipelines, which the crawler should use to trigger scans for all the targets it enumerates.