README
¶
Ocular
an API built onto of Kubernetes that allows you to perform regular or ad-hoc security scans over static software assets. It provides a set of RESTful endpoints that allow you to configure and run security or compliance scanning tools.
Overview
Ocular is a Kubernetes-native API that allows you to perform security scans on static software assets. It provides a set of RESTful endpoints that allow you to configure and run security or compliance scanning tools over static software assets, such as git repositories, container images, or any static content that can be represented on a file system.
It is designed to allow for both regular scans on a scheduled basis or, ad-hoc security scans ran on demand. The system allows for the user to customize not only the scanning tools that are used, but also:
- How scan targets are enumerated (e.g. git repositories, container images, etc.)
- How those scan targets are downloaded into the scanning environment (e.g. git clone, container pull, etc.)
- How the scanning tools are configured and run (e.g. custom command line arguments, environment variables, etc.)
- Where the results are sent (e.g. to a database, to a file, to a cloud storage etc.)
Each of these components can be configured independently, allowing for a high degree of flexibility and customization. Each of the 4 components (enumeration, download, scanning, and results) can be customized via a container image that implements a specific interface, normally through environment variables, command line arguments and file mounts.
Usage
Ocular is configured via the definition of a few "resources", which are static definitions in YAML (or JSON) format and define a container image to run, secrets, or some configuration options for the scanning process.
These resources are then used to configure the scanning process and are read during the execution of container images.
Definitions
Below are a list of all resources that are defined in the system, for more information on each, follow the links to the documentation for each resource:
- Secrets: Used to store sensitive information, such as API keys, passwords, etc. These are stored in Kubernetes secrets and can be referenced in the other resources.
- Downloaders: A container image that will be passed a 'target' (an identifer and optional version) and will be execpted to write the downloaded content to a specific directory in the container filesystem. This will run before the scanners in the same directory.
- Uploader: A container image that will be passed the resulting artifact paths from all scans on a given target and is expected to upload them to a specific location, such as a database, cloud storage, etc.
- Profiles: A collection of containers to run on the downloaded target. Each profile defines a set of container images to run,
along with any command line arguments or environment variables that should be passed to the container. Additionally, profiles will define the artifacts that the scanners will produce, and a list of uploaders to send those artifacts to. - Crawler: A container that will be used to enumerate the targets to scan. It can be ran on a schedule or on demand. The definition can define a set of parameters that should be given when invocated. When the container runs, it will have an authenticated token to the API, and will be expected to call the API to invoke start scans or other crawlers.
Executions
Below are two main types of executions in the system, for more information on each, follow the links to the documentation for each execution type:
-
Pipelines: This accepts a target identifier (normally a URL), an optional target version, the name of the downloader to use, and a profile to run. The execution starts by running the downloader with the target identifier and version set as environment variables. The downloader is expected to download the target content to its current working director. Once the container exists (with code 0), The scanners listed in the profile are executed in parallel, with the target directory mounted as a volume. The scanners should produce artifacts into the 'artifacts' directory in the container filesystem (the path is given as the
OCULAR_ARTIFACTS_DIRenvironment variable). Once all scanners have completed, The uploaders are executed in parallel with the paths of the artifacts produced as command line arguments. -
Search: A search is a run of a crawler, which is a container that will enumerate targets to scan. Searches can be run on a schedule or on demand. It accepts the name of the crawler to run, and any parameters that should be passed to the crawler. The system will mount an authenticated token to the API in the container inside a file, which the environment variable
OCULAR_SERVICE_ACCOUNT_TOKEN_PATHhas the path to this file. The base URL of the API is also provided as an environment variableOCULAR_API_BASE_URL.
OpenAPI
An OpenAPI specification is available in the repo at docs/openapi.yaml.
Additionally, if the server is run in development mode (i.e. OCULAR_ENV=development),
the OpenAPI specification will be served at the /api/swagger/openapi.json endpoint and
a swagger UI will be available at /api/swagger/.
Getting started
Installation via Helm
Please see the Helm chart documentation at artifact hub for the latest version of the chart.
Running locally
See DEVELOPMENT.md for instructions on how to run the application locally.
Documentation
¶
Overview ¶
Package ocular is a package to provide the Ocular application, a code scanning orchestration tool for static application security testing. It is designed to have easily swappable components depending on: what you want to scan with, how you want to enumerate targets, and where you want to upload results to.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
api-server
command
Entrypoint for the API server.
|
Entrypoint for the API server. |
|
extractor
command
Utility image to transfer files between scanners and uploaders.
|
Utility image to transfer files between scanners and uploaders. |
|
hack
|
|
|
generator
command
|
|
|
internal
|
|
|
config
Package config provides the global configuration for Ocular.
|
Package config provides the global configuration for Ocular. |
|
unittest/mocks
Package mocks will contain all the generated mocks for the unit tests.
|
Package mocks will contain all the generated mocks for the unit tests. |
|
unittest/mocks/internal/cluster
Package cluster is a generated GoMock package.
|
Package cluster is a generated GoMock package. |
|
unittest/mocks/pkg/cluster
Package cluster is a generated GoMock package.
|
Package cluster is a generated GoMock package. |
|
unittest/mocks/pkg/storage
Package storage is a generated GoMock package.
|
Package storage is a generated GoMock package. |
|
pkg
|
|
|
api/client
Package client is a package that provides a client for making HTTP requests to the Ocular API.
|
Package client is a package that provides a client for making HTTP requests to the Ocular API. |
|
api/middleware
Package middleware provides middleware for the Ocular API.
|
Package middleware provides middleware for the Ocular API. |
|
api/routes
Package routes (and sub-packages) provides the API routes for the Ocular application.
|
Package routes (and sub-packages) provides the API routes for the Ocular application. |
|
cluster
Package cluster provides function to interact with Kubernetes clusters.
|
Package cluster provides function to interact with Kubernetes clusters. |
|
errors
Package errors provides a way to create and handle errors with types and messages.
|
Package errors provides a way to create and handle errors with types and messages. |
|
identities
Package identities provides the Identity type which represents the identity of a user in the cluster.
|
Package identities provides the Identity type which represents the identity of a user in the cluster. |
|
pipelines
Package pipelines implements the logic to run a pipeline for a target using a profile.
|
Package pipelines implements the logic to run a pipeline for a target using a profile. |
|
resources
Package downloaders provides the Downloader type which represents the init container that will download a static asset (target) to be scanned.
|
Package downloaders provides the Downloader type which represents the init container that will download a static asset (target) to be scanned. |
|
runtime
Package runtime provides functions to manage the runtime environment of the application.
|
Package runtime provides functions to manage the runtime environment of the application. |
|
schemas
Package schemas provides types that will be used in the API and marshalled or unmarshalled from user data
|
Package schemas provides types that will be used in the API and marshalled or unmarshalled from user data |
|
searches
Package searches provides functions to manage invocation of a [Search].
|
Package searches provides functions to manage invocation of a [Search]. |