argus - argus - RAG based vulnerability scanner

项目说明

<p align="center">
<img src="assets/argus-banner.svg" alt="Argus — RAG-powered scanner" width="900"/>
</p>

A RAG-based (Retrie Generation) scanner for Go, Python, Rust, npm/Node.js, Maven/Java, NuGet/.NET, Ruby, and PHP projects — powered by local Ollama models or any OpenAI-compatible API. No cloud lock-in. Your code stays on your machine.

![CI]()
![Go ]()
![Release]()

---

Quick start

Results stream to your terminal with color-coded se; exit code is 1 when findings meet or exceed your --fail-on threshold (default: HIGH).

---

How it works

---

Features

| Category | Feature |
|---|---|
| Privacy | Fully local by default — Ollama + DuckDB on disk, zero external calls after ingest |
| OpenAI compat | Drop-in OpenAI/LiteLLM/vLLM support via --llm-base-url / --embed-base-url |
| Languages | Go, Python, Rust, npm/Node.js, Maven/Ja/.NET, Ruby, PHP |
| Dependency files | go.mod, requirements.txt, Cargo.toml, package.json, package-lock.json, pom.xml, *.csproj, packages.config, Gemfile.lock, composer.lock |
| Data sources | OSV (Go, PyPI, crates.io, npm, Maven, NuGet, RubyGems, Packagist), Go, RustSec, PyPA |
| Feed cache | Zip archi in ~/.cache/argus/feeds with ETag/Last-Modified — repeated ingests are instant |
| Retrieval | Document chunking (512-char o), semantic cosine search, configurable --top-k |
| Accuracy | C — already-fixed ad are silently skipped |
| Accuracy | Alias-aware deduplication — GO-2024-x and C won't double-report |
| C | Numeric CVSS v3 base scores stored and surfaced; --min-cvss filter; --fail-on cvss:N.N exit gate |
| Noise control | --min-se hides LOW/MEDIUM findings; .argusignore suppresses known false positives |
| Output | Color terminal, --output json, --output sarif, --output cyclonedx, --output spdx |
| SBOM | CycloneDX 1.6 JSON and SPDX 2.3 JSON with PURL-linked components and |
| Baseline diff | --baseline-mode diff/update — report only new findings since the last scan (CI noise reduction) |
| Multi-project | --multi ./services/... scans every sub-project in a monorepo in a single run |
| Plugin system | pkg/plugin.EcosystemPlugin interface — add new ecosystems without forking argus |
| Performance | Parallel scan workers, parallel embed workers, jittered-backoff retry, per-scan embed cache (deduplicates identical dep@ calls) |
| Profiles | Named scan profiles (default, fast, ci, thorough) — bundle flags into a single --profile name; define custom profiles in .argus.yaml |
| Attestation | --attest produces a tamper-e Ed25519-signed JSON record; argus it anywhere |
| Web UI | argus serve launches a local dashboard with paginated scan history and DB ecosystem stats |
| DB management | argus db stats/reset/compact — inspect, clear, or the DuckDB file without manual SQL |
| CI | --fail-on threshold flag, SARIF upload, official GitHub Actions composite action |
| CI templates | Ready-to-use pipeline files for GitLab CI, Azure DevOps, Jenkins, CircleCI, CodeBuild, Cloud Build |
| Docker | Slim image (ghcr.io/abhishekamralkar/argus) + bundled image with Ollama included |
| Config | .argus.yaml project config file — commit once, no repeated flags in CI |

---

Prerequisites

| Requirement | | Notes |
|---|---|---|
| Go | 1.26+ | Only needed for go install / building from source |
| Ollama | latest | Required for local model mode |
| DuckDB CLI | optional | For manual DB inspection |

Pull required Ollama models

---

Installation

go install

From source

Download a release binary

Pre-built Linux binaries (amd64 + arm64) are on the Releases page.

Docker — slim image (bring your own Ollama)

Docker — bundled image (Ollama included)

The :bundled tag ships Ollama inside the image. Models are pulled on first run and cached in a named .

Docker Compose

See docker-compose.yml for the full configuration.

---

Commands

ingest — populate the database

Downloads and embeds all databases into a local DuckDB file. Run once, then periodically to pick up new ad.

Feed cache: Downloaded zip archives are stored in ~/.cache/argus/feeds (respects XDG_CACHE_HOME). Subsequent ingest runs send If-None-Match / If-Modified-Since headers and skip re-embedding unchanged feeds. The current cache size is shown by argus status.

data sources:

| Source | Ecosystems |
|---|---|
| OSV | Go, Python, Rust, npm, Maven, NuGet, Ruby, PHP |
| Go Database | Go |
| RustSec | Rust |
| PyPA | Python |

---

status — database health check

---

scan — analyse a project's dependencies

Auto-detects all supported dependency files in the gi.

Text output (default, color-coded):

JSON output:

SARIF output (GitHub Security tab):

CycloneDX 1.6 SBOM:

SPDX 2.3 SBOM:

All scan flags:

| Flag | Default | Description |
|---|---|---|
| --output | text | Output format: text, json, sarif, cyclonedx, spdx |
| --min-se | _(all)_ | Minimum se to report: LOW, MEDIUM, HIGH, CRITICAL |
| --min-cvss | 0 | Minimum CVSS v3 base score to report (0 = report all; skips only findings with a known score below threshold) |
| --fail-on | HIGH | Exit code 1 threshold: LOW, MEDIUM, HIGH, CRITICAL, or cvss:N.N |
| -- | off | Stream per-dependency LLM analysis and add a "Top CVSS" column to the summary table |
| --baseline-mode | full | full = all findings; diff = new only; update = diff + sa |
| --multi | off | Scan multiple project directories; each positional arg is a path (supports ./path/...) |
| --top-k | 10 | search candidates per dependency |
| --workers | 4 | Parallel dependency analysis workers |
| --enhance-query | off | Use LLM to expand search queries before embedding |
| --llm-model | llama3.1:8b | LLM model name |
| --embed-model | nomic-embed-text | Embedding model name |
| --llm-base-url | _(Ollama)_ | LLM API base URL — o OPENAI_BASE_URL / OLLAMA_HOST |
| --embed-base-url | _(Ollama)_ | Embedding API base URL |
| --similarity-threshold | 0.5 | Cosine similarity cutoff (raise to reduce false positives) |
| --timeout | 30 | Scan timeout in minutes (0 = no timeout) |
| --fixes-only | off | Only report packages that have at least one finding with a known fix |
| --profile | _(none)_ | Named scan profile from .argus.yaml or built-in: default, fast, ci, thorough |
| --attest | off | Build and sign a tamper-e attestation after the scan |
| --attestation-out | argus-attestation.json | Path to write the attestation JSON |
| --db | ./vulns.db | DuckDB database path |

---

Multi-project scan

Scan every sub-project in a monorepo with a single command. Each project gets its own .argusignore, and results are aggregated in a single report.

The ./path/... syntax recursively walks the directory tree and picks up every subdirectory that contains at least one recognized dependency file.

---

C filtering

CVSS v3 base scores are computed from ad during ingest and stored alongside se labels. Use them for fine-grained filtering beyond broad se tiers.

C appear in JSON output (top_c, c, c), SARIF rule properties (c), and the -- text summary.

---

baseline — manage scan baselines

The baseline feature eliminates CI noise by only surfacing new since the last scan.

Baseline modes:

| Mode | Behaviour |
|---|---|
| full | Default — report every finding on every run |
| diff | Compare against stored baseline; report only findings not seen before |
| update | Run a diff scan, then save the new results as the updated baseline |

Baseline state is stored in the DuckDB database (a separate scan_baseline table), keyed by the absolute project directory path.

---

Fixes-only mode

When you only want to see actionable findings — packages where an upgrade is a:

---

Named scan profiles

Profiles bundle multiple flags into a single name. Four built-ins ship with argus:

| Profile | Workers | Top-K | Similarity | Min-se | Output |
|---|---|---|---|---|---|
| default | 4 | 10 | 0.35 | _(all)_ | text |
| fast | 8 | 5 | 0.65 | HIGH | text |
| ci | 4 | 10 | 0.55 | _(all)_ | sarif |
| thorough | 2 | 20 | 0.40 | LOW | text |

Define custom profiles in .argus.yaml:

CLI flags always o the acti.

---

— a scan attestation

argus checks the Ed25519 signature on an attestation file and prints its metadata.

Sample output:

Keys are auto-generated in ~/.argus/keys/ on first use. Share signing.pub with downstream consumers so they can without access to the private key.

---

serve — web UI dashboard

argus serve starts a local HTTP server with a li showing scan history and database ecosystem statistics.

The dashboard shows:

The /api/v1/scans endpoint accepts ?limit=N&offset=M query parameters for programmatic paging (default: limit=50, offset=0).

---

db — manage the database

Built-in commands for inspecting, clearing, and compacting the DuckDB file — no manual SQL or file-system surgery needed.

All db subcommands accept --db to target a custom database path.

---

search — ad-hoc semantic search

---

doctor — setup

Checks Ollama/OpenAI connectivity, embedding service, and database health in one command.

Sample output:

---

plugins — list ecosystem parsers

---

completion — shell completions

---

Plugin system

argus exposes a stable Go plugin interface so you can add support for new ecosystems without forking the project.

Interface

Authoring a plugin

1. Create a .go file with package main and //go:build ignore (prevents go build ./... from compiling it as a regular package).
2. Implement EcosystemPlugin and export it as .
3. Build a .so shared library and drop it in ~/.argus/plugins/.

Build and install:

Run argus plugins list to confirm the plugin is loaded, then use argus scan normally — it will detect your custom file patterns automatically.

A complete example lives in examples/plugins/php/plugin.go (note: PHP composer.lock is now a built-in — use this template as a starting point for other ecosystems).

---

Supported ecosystems

| Ecosystem | Dependency file(s) | Ingest sources |
|---|---|---|
| Go | go.mod | OSV/Go, Go |
| Python | requirements.txt | OSV/PyPI, PyPA |
| Rust | Cargo.toml | OS.io, RustSec |
| npm/Node.js | package-lock.json, package.json | OSV/npm |
| Maven/Java | pom.xml | OS |
| NuGet/.NET | packages.config, *.csproj | OS |
| Ruby | Gemfile.lock | OS |
| PHP | composer.lock | OS |

---

OpenAI-compatible API support

argus works with any OpenAI-compatible endpoint — OpenAI, Azure OpenAI, LiteLLM, Ollama's OpenAI layer, vLLM, and others.

Using OpenAI directly:

Using a custom endpoint (LiteLLM, vLLM, etc.):

Auto-detection logic:

1. If OPENAI_API_KEY is set or --llm-base-url / OPENAI_BASE_URL is provided → OpenAI mode
2. Otherwise → Ollama mode (uses OLLAMA_HOST, default )

---

Configuration file

Place .argus.yaml in your project root to avoid repeating flags on every run. CLI flags always take precedence.

---

Ignore list

Create .argusignore in your project root to suppress known false positives or accepted risks:

Lines starting with # are comments. IDs are matched case-insensitively and against ad aliases (suppressing a GO- ID also suppresses its CVE- alias).

---

CI/CD integration

Official GitHub Actions action

The simplest way to add argus to any workflow:

See action.yml and .github/workflows/argus-example.yml for the full reference.

Manual GitHub Actions (Ollama)

Using OpenAI in CI (no Ollama needed)

Baseline diff in CI (report only new findings)

Scan attestation in CI

Other CI/CD platforms

Ready-to-use pipeline templates live in ci-templates/:

| File | Platform |
|---|---|
| gitlab-ci.yml | GitLab CI/CD |
| azure-pipelines.yml | Azure DevOps |
| Jenkinsfile | Jenkins (declarati) |
| circleci-config.yml | CircleCI |
| buildspec.yml | AWS CodeBuild |
| cloudbuild.yaml | Google Cloud Build |

Each template covers install, DB cache, ingest, scan, and SARIF/artifact upload steps. See ci-templates/README.md for per-platform setup instructions.

---

En

| | Description |
|---|---|
| OLLAMA_HOST | Ollama ser (default: ) |
| OPENAI_API_KEY | Enables OpenAI-compatible mode when set |
| OPENAI_BASE_URL | Base URL for OpenAI-compatible endpoint |
| NO_COLOR | Set to any value to disable color output |

---

Inspecting the database

---

Project structure

---

Running tests

---

Roadmap

See ROADMAP.md for planned features and future direction.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

---

License

Apache 2.0 — see LICENSE.

项目信息

开发语言：Go

Star 数：15

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕argus - RAG based vulnerability scanner展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。