Introduction

To get started with Coana, you can either use the CLI directly or follow one of our CI-specific getting started guides (GitHub or GitLab). We recommend that you begin by reading the How does a Coana scan work? section below to build a core understanding of how Coana works.

You can also setup Coana to block pull requests that introduce new reachable vulnerabilities using Coana Guardrail.

How does a Coana scan work?

Coana uses a Command-Line Interface (CLI) to scan your project for vulnerabilities. The CLI itself is wrapped in a Docker image, which comes pre-installed with all the necessary dependencies to run the analysis. When running a vulnerability scan, you point Coana to the root folder of your project (usually a repository) and it then goes through the following process:

It identifies every subproject in the folder (more on subprojects below).
For every subproject, it computes a dependency tree.
Each dependency tree is sent to the Coana servers, where Coana conducts a traditional security scan matching the dependencies against a list of known vulnerabilities.
The results of the traditional scan are reported back to the CLI.
If there are any vulnerabilities, the CLI uses its built-in reachability analysis to determine which of the vulnerabilities are reachable from the entry points of the subprojects. Reachable vulnerabilities are potentially exploitable and should be prioritized. Unreachable vulnerabilities, by definition, are not exploitable and can be ignored. You can learn more about the reachability analysis on the Reachability analysis page.
The aggregated reachability results are sent to the Coana dashboard, where you can later inspect the results. In our Dashboard documentation, you can learn more about how to interpret the Coana scan results in the dashboard.

Subprojects and workspaces

Many repositories are structured as mono-repos containing multiple subprojects. Sometimes these subprojects are managed using tooling like nx (opens in a new tab) or bazel (opens in a new tab), and sometimes they are just independent components contained in the same repository.

Coana is designed to handle mono repositories out-of-the-box. When you run a scan on a mono-repo, Coana will automatically identify the subprojects and scan them independently. You can have multiple subprojects in the same folder (e.g., a package.json and a pom.xml in the same folder) or you can have them in separate folders. The subprojects can be written in different languages and use different package managers.

If you want to exclude a subproject from a scan, you can use the --exclude-dirs <folder1> <folder2>... CLI option.

A subproject can furthermore be divided into workspaces. The exact definition of a workspace depends on the programming language and package manager. For example, in a JavaScript project, a workspace could be a package in a monorepo managed by yarn workspaces (opens in a new tab) or pnpm workspaces (opens in a new tab).

If the same vulnerability affects multiple workspaces or subprojects, Coana will deduplicate the vulnerability and only report it once. Information about the vulnerability that vary between workspaces, such as affected source locations, are still available per-workspace in the details pane pane.

Running a scan

Generate an API key

Go to Settings → API Keys (opens in a new tab) to generate an API key.

Store key

Save the API key in an environment variable named COANA_API_KEY:

export COANA_API_KEY=your-api-key

Store repo url

Store the repository URL of your project in an environment variable named REPO_URL. The repository URL is solely meant as a way for you to identify the project later in the dashboard.

export REPO_URL=your-repo-url

You can also use the --project-name as described below if you don't have a repository URL.

Move to your project's root directory

Change directories (cd) to the root of your project and ensure that all dependencies are installed.

Run the CLI

Initiate the Coana vulnerability analysis with the following command:

docker run \
    -t \
    --pull always \
    --rm \
    -v "$PWD":/project \
    coana/coana:latest \
    coana run /project \
    --api-key $COANA_API_KEY \
    --repo-url $REPO_URL

You can also supply a project name instead of the repo url:

docker run \
    -t \
    --pull always \
    --rm \
    -v "$PWD":/project \
    coana/coana:latest \
    coana run /project \
    --api-key $COANA_API_KEY \
    --project-name nameOfYourProject

💡

A new project is automatically created in Coana when you submit your first report if a project matching its repository url or project name doesn't already exist. There is no reason to manually create the project in Coana first.

💡

You can change the reachability analyzers' memory limit by using the --memory-limit <memoryMB> flag (defaults to 8GB). For example, to increase the memory limit to 16GB, use --memory-limit 16384.

You don't need to install project dependencies, such as running npm install, before using Coana, as Coana will handle the installation of the dependencies for you. However, if you have specific requirements for the installation command, you can also manually install dependencies prior to running Coana.

CLI options

To see all the CLI options run:

docker run --pull always coana/coana:latest coana run --help

Getting Started Reachability Analysis