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.

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

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.

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 \
    -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 \
    -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 dosen't already exist. There is no reason to manually create the project in Coana first.

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 coana/coana:latest coana run --help

Getting Started GitHub