CLI Options for Local Scanner

The CybeDefend CLI provides an efficient way to run local code scans and view results on our platform. It supports Linux, macOS, and Windows and is easily integrated into CI/CD pipelines or used in offline environments.

Usage

cybedefend [command] [flags]

CybeDefend CLI is a CLI tool to interact with the CybeDefend API.

Usage:
  cybedefend [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  login       Authenticate with CybeDefend (OAuth browser flow or PAT)
  logout      Clear stored credentials
  results     Get scan results
  scan        Start a new scan
  version     Show the version of cybedefend

Flags:
      --api-url string    API URL (default "https://api-us.cybedefend.com")
      --region string     Platform region: us or eu (default "us")
      --ci                CI mode
      --config string     Config file (default is $HOME/.cybedefend/config.yaml) (optional)
      --debug             Debug mode
  -h, --help              help for cybedefend

Use "cybedefend [command] --help" for more information about a command.

Installation

You can install the CybeDefend CLI using one of the following methods:

1. Pre-built Binaries

Supported Platforms:

macOS: cybedefend-darwin-amd64 (Intel) or cybedefend-darwin-arm64 (Apple Silicon M1/M2)
Linux: cybedefend-linux-amd64 (64-bit) or cybedefend-linux-386 (32-bit)
Windows: cybedefend-windows-amd64.exe (64-bit) or cybedefend-windows-386.exe (32-bit)

Installation Steps:

Download the latest release for your platform from the GitHub Releases page
Make Executable (Linux/macOS):
chmod +x cybedefend-<platform>

Move to PATH:

sudo mv cybedefend-<platform> /usr/local/bin/cybedefend

Verify Installation:
cybedefend version

2. Build from Source

# Ensure you have Go installed
git clone https://github.com/CybeDefend/cybedefend-cli.git
cd cybedefend-cli
go build -o cybedefend
# Move the binary to your PATH
sudo mv cybedefend /usr/local/bin/
cybedefend version

3. Docker Image

A pre-built Docker image is available on GitHub Container Registry:

docker pull ghcr.io/cybedefend/cybedefend-cli:latest

# Example usage:
docker run --rm -v $(pwd):/app -w /app \
       -e CYBEDEFEND_PAT=$CYBEDEFEND_PAT \
       -e CYBEDEFEND_PROJECT_ID=$CYBEDEFEND_PROJECT_ID \
       ghcr.io/cybedefend/cybedefend-cli:latest scan --dir . --ci

Authentication

The CLI supports two authentication modes. Both store credentials in ~/.cybedefend/credentials.json and are picked up automatically by subsequent commands.

OAuth Browser Flow (recommended for local use)

cybedefend login --region eu

Opens the CybeDefend login page in your default browser. After completing authentication, the CLI stores your session automatically. Access tokens are refreshed transparently when they expire.

cybedefend login --pat YOUR_PAT --region eu

Validates your Personal Access Token and saves it locally. All subsequent commands use it automatically.

# One-time login
cybedefend login --pat YOUR_PAT --region eu

# From now on, no credentials needed per-command
cybedefend scan --dir .
cybedefend results --project-id YOUR_PROJECT_ID

For CI/CD environments, skip cybedefend login entirely and set the PAT as an environment variable:

export CYBEDEFEND_PAT=your_pat_here

Credential Priority Order

--pat flag (highest priority)
CYBEDEFEND_PAT environment variable
pat field in config file
Stored credentials from cybedefend login

Logout

cybedefend logout

Deletes ~/.cybedefend/credentials.json and clears the stored session.

Deprecated: The --api-key flag has been removed. API Keys are no longer supported.

Configuration

Config File (config.yaml in ./, $HOME/.cybedefend, or /etc/cybedefend):

api_url: "https://api-us.cybedefend.com"  # Default if not overridden
pat: "your-personal-access-token"  # PAT from Profile → Personal Access Tokens
project_id: "your-project-id"
# Optional: choose region (us/eu)
# region: "eu"

Environment Variables:

CYBEDEFEND_API_URL - API base URL
CYBEDEFEND_REGION - Platform region (us or eu). Ignored if CYBEDEFEND_API_URL is set
CYBEDEFEND_PAT - Personal Access Token (PAT) for authentication
CYBEDEFEND_PROJECT_ID - Default project ID

Command-Line Flags (override config and env vars):

--region - Platform region (us or eu). Selects https://api-us.cybedefend.com or https://api-eu.cybedefend.com
--api-url - API base URL (manual override; takes precedence over --region)
--project-id - Project ID

Deprecated: The --api-key flag and CYBEDEFEND_API_KEY environment variable have been removed. Use CYBEDEFEND_PAT with a Personal Access Token instead.

Commands

1. `scan`

cybedefend scan [flags]

Starts a new scan by uploading a directory or a pre-zipped file to the CybeDefend platform. By default, the command waits for the scan to complete and displays a summary of findings. Flags:

--dir, -d - Directory to scan (will be zipped before uploading). Cannot be used with --file
--file, -f - Pre-zipped file to scan. Cannot be used with --dir
--project-id - Project ID for the scan (required if not set in config/env)
--region - Platform region: us (default) or eu
--api-url - Manual API URL override (takes precedence over --region)
--wait, -w - Wait for scan completion before exiting (default: true)
--interval - Polling interval in seconds when waiting (default: 5)
--break-on-fail - Exit with error code if scan fails (default: false)
--break-on-severity - Exit with error code if vulnerabilities of specified severity or higher are found. Values: critical, high, medium, low
--ci - CI/CD-friendly output (no colors, ASCII art, or extra formatting)

Examples

# Scan a directory, wait for completion, and show summary (default behavior)
# Assumes PAT is set via `cybedefend login` or CYBEDEFEND_PAT env var
cybedefend scan --dir ./my-app --project-id your-project-id

# Scan a pre-zipped file (PAT must be configured via login or env var)
cybedefend scan --file ./my-app.zip --project-id your-project-id

# Start a scan but don't wait for completion
cybedefend scan --dir ./my-app --project-id your-project-id --wait=false

# Scan, wait, and fail the CI job if the scan process itself fails
cybedefend scan --dir ./my-app --project-id your-project-id --break-on-fail

# Scan, wait, and fail the CI job if any CRITICAL vulnerabilities are found
cybedefend scan --dir ./my-app --project-id your-project-id --break-on-severity critical

# Scan, wait, and fail the CI job if any MEDIUM or higher vulnerabilities are found
cybedefend scan --dir ./my-app --project-id your-project-id --break-on-severity medium

# Select the EU region
cybedefend scan --dir ./my-app --region eu

# Manually override the API URL
cybedefend scan --dir ./my-app --api-url https://api-eu.cybedefend.com

# Change polling interval to 10 seconds
cybedefend scan --dir ./my-app --interval 10

# CI-friendly mode
cybedefend scan --dir ./my-app --ci

2. `results`

cybedefend results [flags]

Retrieves scan results for a project and writes them to a file. By default it fetches every scan type (--type all) in JSON, across all pages, and saves to results.json in the current directory. Flags:

Flag	Default	What it does
`--project-id`	from config / env	Project to fetch results for. Required if not set in the config file or `CYBEDEFEND_PROJECT_ID`
`--type, -t`	`all`	Scan type: `sast`, `sca`, `iac`, `secret`, `cicd`, `container`, or `all`
`--status`	`to_verify,confirmed`	Comma-separated triage states to include: `to_verify`, `confirmed`, `resolved`, `ignored`
`--branch, -b`	all branches	Only return findings on this branch
`--all, -a`	`true`	Fetch every page. Pass `--all=false` to fetch a single page
`--page, -p`	`1`	Page to fetch. Ignored unless you pass `--all=false`
`--grouped, -g`	`false`	Group findings by rule / CVE instead of listing every occurrence. JSON output only
`--scores`	`false`	Add the CVE identifier and the risk scores (priority, CVSS 4.0, EPSS, exploitability) to the output. Applies to the per-occurrence output; grouped output always carries the scores the platform computed
`--output, -o`	`json`	Output format: `json`, `html`, `sarif`, or `markdown`
`--filename, -f`	`results.json`	Output file name
`--filepath`	`.`	Directory to write the file to
`--ci`	`false`	CI/CD-friendly output (no colors or extra formatting)

With --type all the JSON output keeps one array per scan type (sast, sca, iac, secret, cicd, container); the html, sarif and markdown reports flatten them into a single list. --grouped needs a single scan type — it has no effect while --type is all.

Choosing which triage states to export

--status decides which triage states end up in the file. The default, to_verify,confirmed, is the set of findings that still need attention: what you have already resolved or ignored stays out.

Value	Meaning
`to_verify`	Not triaged yet
`confirmed`	Triaged and accepted as a real finding
`resolved`	Fixed
`ignored`	Deliberately dismissed

Any other value is rejected before a request is sent. not_exploitable is a state you will see in the platform, but the API does not accept it as a filter value, so you cannot ask for it here.

Your exports get smaller, and that is the fix. Earlier CLI versions sent this filter in a spelling the API silently discarded, so every export contained every state — resolved and ignored findings included. The filter now reaches the API. If a pipeline of yours counts rows in results.json or feeds them into a ticketing system, expect fewer rows and adjust the threshold.

# Before: the default export returned every state, whatever you asked for
cybedefend results --project-id $PROJECT_ID --type sca

# After: ask for the extra states explicitly to get a comparable volume
cybedefend results --project-id $PROJECT_ID --type sca \
                   --status to_verify,confirmed,resolved,ignored

Findings in the not_exploitable state were part of the old over-delivered export and cannot be requested back, so even the four-state filter above returns slightly fewer rows than the old default.

Every finding in a JSON export carries its own state in currentState, so a file is self-describing and you can re-filter it afterwards without another call:

{
  "id": "6f1c…",
  "path": "src/auth/session.ts",
  "branch": "main",
  "currentState": "to_verify",
  "vulnerability": { "name": "…", "severity": "…" }
}

currentState is present in the JSON output only — the html, sarif and markdown reports do not show the triage state. --status is also not applied to --grouped --type container, which returns grouped images through a separate endpoint.

--status is a recent addition. If your CLI answers unknown flag: --status, upgrade the binary from the releases page.

Examples

# Every scan type, findings that still need attention (the default)
cybedefend results --project-id your-project-id

# Only what you have dismissed, to audit your own triage decisions
cybedefend results --project-id your-project-id --type sca --status ignored,resolved

# Everything the API will filter on, for a full snapshot
cybedefend results --project-id your-project-id --status to_verify,confirmed,resolved,ignored

# SAST findings on one branch, as SARIF, for code scanning upload
cybedefend results --project-id your-project-id --type sast --branch main \
                   --output sarif --filename results.sarif

# SCA findings with the CVE identifiers and risk scores
cybedefend results --project-id your-project-id --type sca --scores

# SCA findings grouped by CVE instead of one row per occurrence
cybedefend results --project-id your-project-id --type sca --grouped

# A single page instead of the whole project
cybedefend results --project-id your-project-id --type sast --all=false --page 2

3. `version`

Displays the CLI version:

cybedefend version

4. `completion`

Generates shell autocompletion for bash, zsh, etc.:

cybedefend completion [shell]

CI/CD Integration

Combine the scan and results commands in your pipelines. The scan command’s --wait, --break-on-fail, and --break-on-severity flags are particularly useful for controlling pipeline flow based on scan outcomes. For example, in GitHub Actions:

- name: Install CybeDefend CLI # Or use the Docker image method
  run: |
    # Download commands...
    curl -L https://github.com/CybeDefend/cybedefend-cli/releases/latest/download/cybedefend-linux-amd64 -o cybedefend
    chmod +x cybedefend
    sudo mv cybedefend /usr/local/bin/

- name: Run security scan and break on High severity
  env:
    CYBEDEFEND_PAT: ${{ secrets.CYBEDEFEND_PAT }}
  run: cybedefend scan --dir ./ --ci \
         --project-id ${{ secrets.CYBEDEFEND_PROJECT_ID }} \
         --break-on-severity high # Fail build if High or Critical vulns found

# Optionally, fetch detailed results artifact if needed, e.g., for reporting
# This step might only run if the previous one succeeded, depending on workflow setup
- name: Fetch Detailed Results as SARIF
  env:
    CYBEDEFEND_PAT: ${{ secrets.CYBEDEFEND_PAT }}
  run: cybedefend results --project-id ${{ secrets.CYBEDEFEND_PROJECT_ID }} \
                          --output sarif --filename results.sarif --ci

# - name: Upload SARIF results (Example using GitHub action)
#   uses: github/codeql-action/upload-sarif@v2
#   with:
#     sarif_file: results.sarif

Use --ci for minimal logs during the scan. The --break-on-* flags allow automatic build failure based on your security policies. You can still use cybedefend results to fetch detailed reports if the scan passes the break conditions or if you need the data regardless.

CybeDefend

Platform Overview

Getting Started

Agent & AI Integration

IDE Integrations

Code Scanning

Container Scanning

Managing Vulnerabilities

Issue Tracker Integrations

Notifications

Usage

Installation

1. Pre-built Binaries

2. Build from Source

3. Docker Image

Authentication

OAuth Browser Flow (recommended for local use)

Credential Priority Order

Logout

Configuration

Commands

1. `scan`

Examples

2. `results`

Choosing which triage states to export

Examples

3. `version`

4. `completion`

CI/CD Integration

​Usage

​Installation

​1. Pre-built Binaries

​2. Build from Source

​3. Docker Image

​Authentication

​OAuth Browser Flow (recommended for local use)

​PAT-Based Login (recommended for CI/CD)

​Environment Variable (no login step)

​Credential Priority Order

​Logout

​Configuration

​Commands

​1. scan

​Examples

​2. results

​Choosing which triage states to export

​Examples

​3. version

​4. completion

​CI/CD Integration

Usage

Installation

1. Pre-built Binaries

2. Build from Source

3. Docker Image

Authentication

OAuth Browser Flow (recommended for local use)

PAT-Based Login (recommended for CI/CD)

Environment Variable (no login step)

Credential Priority Order

Logout

Configuration

Commands

1. `scan`

Examples

2. `results`

Choosing which triage states to export

Examples

3. `version`

4. `completion`

CI/CD Integration