@eurekadevsecops/radar 1.8.4 → 1.9.1

package/.github/workflows/radar.yaml

@@ -1,4 +1,4 @@
-name: Eureka Radar
+name: Radar CLI
 
 on:
   workflow_dispatch:
@@ -8,9 +8,9 @@ on:
       - main
 
 jobs:
-  radar_scan:
+  scan:
     # Radar scanner repo: https://github.com/EurekaDevSecOps/radarctl
-    name: Radar Scan
+    name: Scan
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo

package/README.md

@@ -1,64 +1,331 @@
-<pre>
-               _            
- _ __ __ _  __| | __ _ _ __ 
-| '__/ _` |/ _` |/ _` | '__|
-| | | (_| | (_| | (_| | |   
-|_|  \__,_|\__,_|\__,_|_|
-</pre>
+<div align="center" style="text-align:center;">
 
-# Introduction
+<p align="center">
+  <img src="assets/radar.png" alt="Eureka Radar Logo" width="320"/>
+</p>
 
-radarctl is a command-line interface for Radar, an open-source orchestrator of security scanners. Radar is part of the Eureka DevSecOps platform.
+# Radar CLI
+### One command. Complete AppSec coverage.
+
+<!-- ![Build](https://github.com/eurekadevsecops/radarctl/actions/workflows/test.yml/badge.svg) -->
+![Node](https://img.shields.io/badge/Node.js-22.x-blue?logo=node.js)
+![npm version](https://img.shields.io/npm/v/@eurekadevsecops/radar?color=2b82f6&label=NPM)
+![License](https://img.shields.io/github/license/eurekadevsecops/radarctl?color=green)
+
+</div>
+
+---
+
+## Overview
+
+**Radar CLI** is a command-line tool that orchestrates multiple application security scanners — for code, dependencies, containers, and secrets — in one unified package. We've put a lot of effort into making Radar CLI easy to use for developers and easy to integrate into CI/CD pipelines. Check out our accompanying [GitHub Action for Radar CLI](https://github.com/EurekaDevSecOps/scan-action).
+
+With Radar CLI, you can:
+- Run **SAST**, **SCA**, **container**, and **secret scanning** locally or in CI/CD pipelines.
+- Generate **unified SARIF reports** compatible with industry-standard security and vulnerability analysis tools.
+- Optionally upload results to **Eureka ASPM** for centralized tracking, deduplication, and prioritization.
+
+---
+
+Telemetry is **off by default** — nothing is uploaded unless you explicitly enable it.
+
+---
 
 ## Requirements
 
-- Node.js version 22.17.0 or higher
-- Docker
+- **Node.js** 22.17.0 or higher  
+- **Docker** (for containerized scanners)
+
+---
 
 ## Installation
 
-Install the Radar CLI on the command-line using [NPM](https://npmjs.com):
+Install globally using **npm**:
 
 ```bash
 npm i -g @eurekadevsecops/radar
+````
+
+Verify the installation:
+
+```bash
+radar --version
 ```
 
+---
+
 ## Getting Started
 
-Run the Radar CLI:
+Run the CLI to view available commands:
 
 ```bash
 radar
 ```
 
-You will get a list of available commands:
-```bash
-COMMANDS 
-  help      display help              
-  scan      scan for vulnerabilities  
-  scanners  display available scanners 
+Example output:
+
+```
+COMMANDS
+  help      display help
+  scan      scan for vulnerabilities
+  scanners  display available scanners
 ```
 
-View help page for each command by using `help` on the command-line:
+You can view help for any command:
 
 ```bash
-radar help
+radar help scan
 ```
 
+---
+
 ## Running a Scan
 
-Run a scan on the source code in the current working directory:
+To scan the current working directory:
 
 ```bash
 radar scan
 ```
 
-Refer to help for the `scan` command for more information.
+You can also specify scanners to use:
 
 ```bash
-radar help scan
+radar scan -s opengrep,gitleaks,grype
+```
+
+Output a SARIF report:
+
+```bash
+radar scan -s opengrep,gitleaks,grype -o report.sarif
+```
+
+---
+
+## Supported Scanners
+
+All scanners in Radar are fully containerized for consistency and isolation. When you run a scan, Radar CLI automatically launches the corresponding scanner inside a Docker container. This ensures clean, reproducible results without needing to install each scanner locally. A working Docker Engine is required to run Radar scanners, and the container images for all supported scanners are publicly available on the GitHub Container Registry.
+
+| By Scanner                                                                        | Categories             | Description |
+| --------------------------------------------------------------------------------- | ---------------------- | ----------- |
+| [Dep-Scan](https://github.com/owasp-dep-scan/dep-scan)                            | **SCA**                | OWASP dep-scan is a next-generation security and risk audit tool based on known vulnerabilities, advisories, and license limitations for project dependencies. Scan most application code - local repos, Linux container images, Kubernetes manifests, and OS - to identify known CVEs with prioritization. |
+| [Gitleaks](https://github.com/gitleaks/gitleaks)                                  | **Secrets**            | Gitleaks is a tool for detecting secrets like passwords, API keys, and tokens. |
+| [Grype](https://github.com/anchore/grype)                                         | **SCA**, **Container** | Scans the contents of a container image or filesystem to find known vulnerabilities. Find vulnerabilities for language-specific packages and major operating system packages. Supports Docker, OCI and Singularity image formats. |
+| [Opengrep](https://github.com/opengrep/opengrep)                                  | **SAST**               | Opengrep is an ultra-fast static code analysis engine to find security issues in code. Opengrep supports 30+ languages. |
+| [Veracode SCA](https://www.veracode.com/products/software-composition-analysis/)  | **SCA**                | Effectively identify open-source risks with unmatched precision, ensuring secure and compliant code. Leverages a proprietary database to accurately and promptly detect new vulnerabilities. |
+
+Scanners grouped by category:
+
+| By Category       | Description                                      | Scanners                                                                                          |
+| ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| **SAST**          | Detects insecure code patterns                   | [Opengrep](https://github.com/opengrep/opengrep)                                                  |
+| **Secrets**       | Finds hardcoded credentials                      | [Gitleaks](https://github.com/gitleaks/gitleaks)                                                  |
+| **SCA**           | Detects vulnerable package dependencies          | [Veracode SCA](https://www.veracode.com/products/software-composition-analysis/), [Grype](https://github.com/anchore/grype), [Dep-Scan](https://github.com/owasp-dep-scan/dep-scan) |
+| **Container**     | Scans Docker, OCI, and Singularity image formats | [Grype](https://github.com/anchore/grype)                                                         |
+
+Veracode SCA (formerly SourceClear) scanner requires the SRCCLR_API_TOKEN environment variable. If not present or valid, scanning with Veracode SCA will not work. Read more about it in [Veracode SCA online documentation](https://docs.veracode.com/r/Veracode_SCA_Agent_Environment_Variables#srcclr_api_token).
+
+---
+
+### More on the `radar scan` command
+
+```bash
+USAGE
+  radar scan [OPTIONS] [TARGET]
+```
+
+Scans your source code and dependencies for vulnerabilities.
+If no target is specified, the current working directory is scanned.
+
+**OPTIONS**
+
+| Option             | Description                                                                                         |
+| ------------------ | --------------------------------------------------------------------------------------------------- |
+| `-c, --categories` | List of scanner categories (e.g. `sast`, `sca`, `secrets`).                                         |
+| `-s, --scanners`   | Comma-separated list of scanners to run. Use `radar scanners` to list available ones.               |
+| `-o, --output`     | Output findings into a SARIF file.                                                                  |
+| `-d, --debug`      | Log detailed debug info to stdout.                                                                  |
+| `-q, --quiet`      | Suppress stdout logging (except errors).                                                            |
+| `-f, --format`     | Output format for severity display: `security` (high/moderate/low) or `sarif` (error/warning/note). |
+| `-e, --escalate`   | Treat specified lower severities as high (e.g. `--escalate=moderate,low`).                          |
+| `-l, --local`      | Run a local scan (don't upload scan findings to Eureka).                                            |
+
+**PARAMETERS**
+
+| Parameter | Description                                             |
+| --------- | ------------------------------------------------------- |
+| `TARGET`  | (Optional) Path to scan. Defaults to current directory. |
+
+#### Category and Scanner Selection
+
+* `--categories` lets you run all scanners in one or more categories.
+  Example: `--categories=sca,sast`
+* `--scanners` lets you choose specific scanners by name.
+  Example: `--scanners=opengrep,depscan`
+* Both can be combined — Radar CLI will run scanners that match *both* filters.
+
+#### Severity Formats
+
+| Format     | Example Severities     |
+| ---------- | ---------------------- |
+| `security` | high / moderate / low  |
+| `sarif`    | error / warning / note |
+
+You can also **escalate severities**:
+
+```bash
+# Treat moderates and lows as highs
+radar scan -e moderate,low
+```
+
+Or:
+
+```bash
+# Treat warnings and notes as errors
+radar scan -f sarif -e warning,note
+```
+
+#### Exit Codes
+
+An exit code of `0` means the scan passed with no issues. Any other code means the scan failed — either due to new vulnerabilities found or an error during the scanning process.
+
+| Code    | Meaning                                 |
+| ------- | --------------------------------------- |
+| `0`     | Clean and successful scan.              |
+| `1`     | Invalid command, arguments, or options. |
+| `8–15`  | New vulnerabilities found.              |
+| `>=16`  | Aborted due to unexpected error.        |
+
+#### Examples
+
+Scan current directory:
+```bash
+radar scan
 ```
 
-## Contributing guide
+Scan a specific path:
+```bash
+radar scan /my/repo/dir
+```
+
+Save findings into a SARIF file:
+```bash
+radar scan -o report.sarif
+```
+
+Run only dependency and code scanners:
+```bash
+radar scan -c sca,sast
+```
+
+Run specific scanners:
+```bash
+radar scan -s depscan,opengrep
+```
+
+Enable debug logs:
+```bash
+radar scan --debug
+```
+
+Quiet mode (errors only):
+```bash
+radar scan --quiet
+```
+
+Display findings in SARIF-style severities:
+```bash
+radar scan -f sarif
+```
+
+Treat moderates and lows as highs:
+```bash
+radar scan -e moderate,low
+```
+
+---
+
+## Example Workflows
+
+### Local Scan (no uploads)
+
+Runs entirely on your machine — by default, Radar CLI doesn’t upload any findings. Your vulnerabilities stay local and private.
+
+```bash
+radar scan -s opengrep,gitleaks,grype -o report.sarif
+```
+
+### Upload Findings to Eureka ASPM
+
+See all findings in one place with deduplication, trend tracking, and risk prioritization. To upload results to **Eureka ASPM**, provide your API credentials via two environment variables: `EUREKA_AGENT_TOKEN` (your API token) and `EUREKA_PROFILE` (your profile ID). When these are set, Radar CLI automatically uploads results after each scan — letting you view your full scan history and all findings in the **Eureka ASPM Dashboard**.
+
+```bash
+export EUREKA_AGENT_TOKEN=<your token>
+export EUREKA_PROFILE=<your profile ID>
+
+radar scan -s opengrep,gitleaks,grype
+```
+
+NOTE: To prevent Radar CLI from uploading scan findings even when you have `EUREKA_AGENT_TOKEN` and `EUREKA_PROFILE` set, you can pass the `-l/--local` option on the command line.
+
+---
+
+## Why Upload Findings to Eureka ASPM?
+
+**Eureka ASPM** extends Radar CLI with powerful visibility and collaboration features:
+
+* **Single Source of Truth:** Aggregate findings from all scanners and repos in one place.
+* **Less Noise, More Signal:** Automatically de-duplicate findings and prioritize risks contextually.
+* **Faster Fixes:** See ownership, severity, and remediation guidance for each issue.
+* **Track Progress:** View how your project’s security posture improves over time.
+* **Free for Open Source:** Open source projects get full access at no cost.
+
+**Sign up for a free account at [eurekadevsecops.com](https://eurekadevsecops.com)**
+
+---
+
+## Telemetry & Privacy
+
+Telemetry is **off by default**.
+Radar does **not** send any data externally unless you explicitly provide:
+
+* `EUREKA_AGENT_TOKEN`
+* `EUREKA_PROFILE`
+
+When provided:
+
+* Findings are securely uploaded to **Eureka ASPM**
+* You gain **dashboards, trend analysis, and contextual prioritization**
+
+When omitted:
+
+* Scans remain **fully local**
+
+---
+
+## 🧰 Troubleshooting
+
+| Issue                                         | Cause                               | Solution                                                  |
+| --------------------------------------------- | ----------------------------------- | --------------------------------------------------------- |
+| ❌ `report.sarif` not found                   | Scan failed or invalid scanner list | Check scanner names and ensure Docker is running          |
+| ⚠️ No findings uploaded                       | Missing or invalid token/profile    | Set `EUREKA_AGENT_TOKEN` and `EUREKA_PROFILE`             |
+| 🧱 `radar: command not found`                 | CLI not installed globally          | Run `npm i -g @eurekadevsecops/radar` again               |
+
+---
+
+## Contributing
+
+Contributions are welcome!
+See our [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and development guidelines.
+
+---
+
+## License
+
+Radar CLI is licensed under the terms of the **GPL v3 License** — © Eureka DevSecOps Inc.
+
+---
+
+## Support
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md)
+* Issues & feature requests: [GitHub Issues](https://github.com/eurekadevsecops/radarctl/issues)
+* Security: [security@eurekadevsecops.com](mailto:security@eurekadevsecops.com)

package/azure-pipelines.yml

@@ -0,0 +1,27 @@
+# Run Radar CLI scan via Azure Pipelines
+
+trigger:
+- main
+
+pool:
+  vmImage: ubuntu-latest
+
+steps:
+- task: NodeTool@0
+  inputs:
+    versionSpec: '22.x'
+  displayName: 'Install Node.js'
+
+- script: npm i -g @eurekadevsecops/radar
+  displayName: Install Radar CLI
+
+- script: radar && radar scanners
+  displayName: Verify Radar install
+
+- script: radar scan -s gitleaks,grype,opengrep,veracode-sca
+  displayName: Run Radar scan
+  env:
+    EUREKA_AGENT_TOKEN: $(EUREKA_AGENT_TOKEN)
+    SRCCLR_API_TOKEN: $(SRCCLR_API_TOKEN)
+    VERACODE_API_KEY_ID: $(VERACODE_API_KEY_ID)
+    VERACODE_API_KEY_SECRET: $(VERACODE_API_KEY_SECRET)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eurekadevsecops/radar",
-  "version": "1.8.4",
+  "version": "1.9.1",
   "description": "Radar is an open-source orchestrator of security scanners.",
   "homepage": "https://www.eurekadevsecops.com/radar",
   "keywords": [

package/scanners/veracode-sca/about.toml

@@ -0,0 +1,5 @@
+name = "veracode-sca"
+title = "Veracode SCA"
+description = "Finds known vulnerabilities in dependencies. Requires SRCCLR_API_TOKEN."
+categories = [ "SCA" ]
+cmd = "${assets}/run.sh ${target} ${assets} ${output}"

package/scanners/veracode-sca/run.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+set -e
+
+# Parameters:
+# $1 - Path to the source code folder that should be scanned
+# $2 - Path to the assets folder
+# $3 - Path to the output folder where scan results should be stored
+###
+
+# Expand relative paths
+APP_DIR=$(cd $1; pwd)
+CFG_DIR=$(cd $2; pwd)
+OUT_DIR=$(cd $3; pwd)
+
+docker run --rm \
+    -v "${APP_DIR}":/home/luser/app \
+    -v "${CFG_DIR}":/tmp/radar-input \
+    -v "${OUT_DIR}":/tmp/radar-output \
+    -e SRCCLR_API_TOKEN=${SRCCLR_API_TOKEN} \
+    ghcr.io/eurekadevsecops/radar-veracode-sca 2>&1

package/src/commands/scan.js

@@ -20,6 +20,7 @@ module.exports = {
     { name: 'DEBUG', short: 'd', long: 'debug', type: 'boolean', description: 'log detailed debug info to stdout' },
     { name: 'ESCALATE', short: 'e', long: 'escalate', type: 'string', description: 'severities to treat as high/error' },
     { name: 'FORMAT', short: 'f', long: 'format', type: 'string', description: 'severity format' },
+    { name: 'LOCAL', short: 'l', long: 'local', type: 'boolean', description: 'local scan (no upload of findings to Eureka)' },
     { name: 'OUTPUT', short: 'o', long: 'output', type: 'string', description: 'output SARIF file' },
     { name: 'QUIET', short: 'q', long: 'quiet', type: 'boolean', description: 'suppress stdout logging' },
     { name: 'SCANNERS', short: 's', long: 'scanners', type: 'string', description: 'list of scanners to use' }
@@ -60,6 +61,15 @@ module.exports = {
     'security' severity format. Findings can also be displayed as errors, warnings,
     and notes. This is the 'sarif' severity format.
 
+    Runs entirely on your machine — by default, Radar CLI doesn’t upload any findings.
+    Your vulnerabilities stay local and private. To upload results to Eureka ASPM,
+    provide your API credentials via two environment variables: 'EUREKA_AGENT_TOKEN'
+    (your API token) and 'EUREKA_PROFILE' (your profile ID). When these are set, Radar CLI
+    automatically uploads results after each scan — letting you view your full scan 
+    history and all findings in the Eureka ASPM Dashboard. To prevent Radar CLI from
+    uploading scan findings even when you have 'EUREKA_AGENT_TOKEN' and 'EUREKA_PROFILE'
+    set, you can pass the LOCAL option on the command line.
+
     Exit codes:
          0 - Clean and successful scan. No errors, warnings, or notes.
          1 - Bad command, arguments, or options. Scan not completed.
@@ -76,6 +86,7 @@ module.exports = {
   examples: [
     '$ radar scan ' + '(scan current working directory)'.grey,
     '$ radar scan . ' + '(scan current working directory)'.grey,
+    '$ radar scan --local ' + '(run a local scan / no uploads to Eureka)'.grey,
     '$ radar scan -d' + '(turn debug mode on)'.grey,
     '$ radar scan --debug' + '(turn debug mode on)'.grey,
     '$ radar scan /my/repo/dir ' + '(scan target directory)'.grey,
@@ -144,9 +155,13 @@ module.exports = {
     if (!categories.length) throw new Error(`CATEGORIES must be one or more of '${availableCategories.join("', '")}', or 'all'`)
     if (!scanners.length) throw new Error('No available scanners selected.')
 
+    if (!telemetry.enabled || args.LOCAL) {
+      log(`INFO: Running a local scan.\n`)
+    }
+
     // Send telemetry: scan started.
     let scanID = undefined
-    if (telemetry.enabled) {
+    if (telemetry.enabled && !args.LOCAL) {
       // TODO: Should pass scanID to the server; not read it from the server.
       try {
         const res = await telemetry.send(`scans/started`, {}, { scanners: scanners.map((s) => s.name) })
@@ -169,7 +184,7 @@ module.exports = {
     // Send telemetry: git metadata.
     const metadata = git.metadata(target)
     if (metadata.type === 'error') throw new Error(`${metadata.error.code}: ${metadata.error.details}`)
-    if (telemetry.enabled && scanID) {
+    if (telemetry.enabled && scanID && !args.LOCAL) {
       let res = await telemetry.send(`scans/:scanID/metadata`, { scanID }, { metadata })
       if (!res.ok) log(`WARNING: Scan metadata (stage 1) telemetry upload failed: [${res.status}] ${res.statusText}: ${await res.text()}`)
       res = await telemetry.sendSensitive(`scans/:scanID/metadata`, { scanID }, { metadata })
@@ -186,7 +201,7 @@ module.exports = {
     catch (error) {
       log(`\n${error}`)
       if (!args.QUIET) log('Scan NOT completed!')
-      if (telemetry.enabled) {
+      if (telemetry.enabled && !args.LOCAL) {
         const res = await telemetry.send(`scans/:scanID/failed`, { scanID })
         if (!res.ok) log(`WARNING: Scan status (not completed) telemetry upload failed: [${res.status}] ${res.statusText}: ${await res.text()}`)
       }
@@ -202,14 +217,14 @@ module.exports = {
     if (outfile) fs.writeFileSync(outfile, JSON.stringify(results.sarif, null, 2))
 
     // Send telemetry: scan results.
-    if (telemetry.enabled && scanID) {
+    if (telemetry.enabled && scanID && !args.LOCAL) {
       const res = await telemetry.sendSensitive(`scans/:scanID/results`, { scanID }, { findings: results.sarif, log: results.log })
       if (!res.ok) log(`WARNING: Scan results telemetry upload failed: [${res.status}] ${res.statusText}: ${await res.text()}`)
     }
 
     // Analyze scan results: group findings by severity level.
     let summary
-    if (telemetry.enabled && scanID) {
+    if (telemetry.enabled && scanID && !args.LOCAL) {
       const analysis = await telemetry.receiveSensitive(`scans/:scanID/summary`, { scanID })
       if (!analysis?.findingsBySeverity) throw new Error(`Failed to retrieve analysis summary for scan '${scanID}'`)
       summary = analysis.findingsBySeverity
@@ -218,7 +233,7 @@ module.exports = {
     }
 
     // Send telemetry: scan summary.
-    if (telemetry.enabled && scanID) {
+    if (telemetry.enabled && scanID && !args.LOCAL) {
       const res = await telemetry.send(`scans/:scanID/completed`, { scanID }, summary)
       if (!res.ok) log(`WARNING: Scan status (completed) telemetry upload failed: [${res.status}] ${res.statusText}: ${await res.text()}`)
     }
@@ -228,7 +243,7 @@ module.exports = {
       log()
       SARIF.visualizations.display_findings(summary, args.FORMAT, log)
       if (outfile) log(`Findings exported to ${outfile}`)
-      SARIF.visualizations.display_totals(summary, args.FORMAT, log, telemetry.enabled && scanID)
+      SARIF.visualizations.display_totals(summary, args.FORMAT, log, telemetry.enabled && scanID && !args.LOCAL)
     }
 
     // Determine the correct exit code.