If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/future-architect/vuls shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 8 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live future-architect/vuls repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/future-architect/vuls.

What it runs against: a local clone of future-architect/vuls — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in future-architect/vuls | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of future-architect/vuls. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/future-architect/vuls.git
#   cd vuls
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of future-architect/vuls and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "future-architect/vuls(\\.git)?\\b" \\
  && ok "origin remote is future-architect/vuls" \\
  || miss "origin remote is not future-architect/vuls (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/vuls/main.go" \\
  && ok "cmd/vuls/main.go" \\
  || miss "missing critical file: cmd/vuls/main.go"
test -f "cmd/scanner/main.go" \\
  && ok "cmd/scanner/main.go" \\
  || miss "missing critical file: cmd/scanner/main.go"
test -f "config/config.go" \\
  && ok "config/config.go" \\
  || miss "missing critical file: config/config.go"
test -f "cache/db.go" \\
  && ok "cache/db.go" \\
  || miss "missing critical file: cache/db.go"
test -f "constant/constant.go" \\
  && ok "constant/constant.go" \\
  || miss "missing critical file: constant/constant.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/future-architect/vuls"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Vuls is an agent-less vulnerability scanner written in Go that detects security vulnerabilities across Linux, FreeBSD, containers, WordPress, and programming language libraries by scanning installed packages against NVD and other vulnerability databases. It runs without deploying agents on target systems, generates automated reports, and integrates with alerting platforms like Slack, email, and cloud services (AWS, Azure). Monolithic Go project with clear separation: cmd/ contains two entry points (cmd/vuls/main.go for CLI, cmd/scanner/main.go for agent), config/ handles TOML/JSON configuration loading and platform-specific OS scanning modes, cache/ implements BoltDB persistence, and specialized packages for cloud integrations (AWS, Azure, Google Chat, Slack, HTTP webhooks). No internal pkg/ directory yet; packages are top-level organized by concern.

System administrators and DevOps engineers managing production Linux/FreeBSD infrastructure who need to continuously monitor for vulnerabilities without downtime-causing manual updates, and security teams that require automated vulnerability reporting across multiple servers and containers.

Production-ready. The project shows active development (dependencies updated to 2025, Go 1.26 support), comprehensive CI/CD via GitHub Actions (build.yml, golangci.yml, docker-publish.yml, goreleaser.yml), structured test files throughout (config_test.go, cache/bolt_test.go, portscan_test.go), and clear versioning via goreleaser. Last meaningful updates in early 2025 indicate ongoing maintenance.

Moderate risk. The dependency graph is moderately large (mainline imports ~30+ external packages including aquasecurity/trivy, AWS SDK v2, Azure SDK, Google container registry). Single-maintainer concerns exist (future-architect org), though the 2.8MB Go codebase suggests multi-contributor history. Breaking changes possible in vulnerability database schema (MaineK00n/vuls-data-update and MaineK00n/vuls2 are pre-release alpha versions). Database update frequency (trivy-db, trivy-java-db) is critical but external dependency.

Active development on v3-alpha with MaineK00n/vuls2 v0.0.1-alpha dependency and vuls-data-update module (0.0.0-20260428075914-ea21d0d8e4c9), indicating schema or data format migration. Recent GitHub Actions workflows (scorecard.yml, diet-check.yml) suggest security and binary size focus. Trivy integration updated to 0.69.2 (late 2024).

git clone https://github.com/future-architect/vuls.git && cd vuls && make build (or make install from GNUmakefile). For Docker: docker build -t vuls:latest . && docker run vuls --help.

Daily commands: make build produces binary in current dir. For local scan: ./vuls scan --config config.toml. For Docker: docker run --rm -v /etc:/etc:ro vuls scan. See Dockerfile for multi-stage build (Go 1.26 base).

• cmd/vuls/main.go — Primary CLI entry point for the vulnerability scanner; all scan workflows originate here
• cmd/scanner/main.go — Agent scanner entry point; handles remote scanning operations on target systems
• config/config.go — Core configuration parsing and validation; defines scan targets, notification channels, and scan modes
• cache/db.go — Vulnerability database caching layer; critical for scan performance and offline operation
• constant/constant.go — Global constants and configuration values that propagate throughout the scanner
• .golangci.yml — Linter configuration enforcing code quality standards that all contributors must follow
• GNUmakefile — Build and development workflow; documents how to compile, test, and release the scanner

• CLI (cmd/vuls/main.go) (Cobra (CLI framework)) — User-facing entry point; parses arguments, loads config, orchestrates scan and report workflows
  • Failure mode: If CLI fails, no scan is initiated; config parsing errors prevent execution
• Config Loader (config/*) (TOML, JSON parsers) — Loads TOML/JSON config, validates targets, notification settings, and scan modes
  • Failure mode: Invalid config blocks all scans; missing credentials cause notification failures
• Scanner Engine — undefined

Add a New Notification Channel

1. Create a new configuration struct in config/ (e.g., config/newnotifierconf.go) with fields for credentials and endpoint (config/newnotifierconf.go)
2. Add the configuration type to the main Config struct in config/config.go (config/config.go)
3. Implement notification logic as a handler function that integrates with the reporting pipeline (config/newnotifierconf.go)
4. Update the TOML loader in config/tomlloader.go to parse the new notifier settings (config/tomlloader.go)

Add Support for a New Vulnerability Source

1. Create a new configuration in config/vulnDictConf.go or extend it to recognize the new source (config/vulnDictConf.go)
2. Update the cache layer in cache/db.go to query and store data from the new source (cache/db.go)
3. Register the source in the main configuration parsing flow in config/config.go (config/config.go)

Add a New Scan Mode (OS/Container Type)

1. Define the scan mode constant in config/scanmode.go (config/scanmode.go)
2. Add mode-specific configuration fields in config/config.go (config/config.go)
3. Update config/tomlloader.go to parse the new mode from TOML configurations (config/tomlloader.go)
4. Implement mode detection and handling in config/os.go for OS fingerprinting (config/os.go)

• Go — Single static binary for agent-less remote scanning; minimal dependencies and fast execution on target systems
• BoltDB (embedded KV store) — Lightweight offline caching of vulnerability data; no external database required for standalone operation
• TOML configuration — Human-readable configuration for scan targets, notification channels, and OS detection rules
• Trivy integration — Leverages mature container/OCI image vulnerability scanning; composable with system package scanning
• AWS/Azure SDK — Native cloud integration for scanning distributed EC2/VM instances across multiple accounts

• Agent-less architecture via SSH/agentless protocols

  • Why: Reduces operational overhead and security footprint on targets
  • Consequence: Requires network access and credentials; cannot perform deep monitoring on systems where SSH is disabled

• Local BoltDB caching instead of central vulnerability DB

  • Why: Enables offline scanning and reduces dependency on external services
  • Consequence: Vulnerability data must be manually updated; multiple scanner instances maintain separate caches

• Configuration via static TOML files

  • Why: Simple, version-controllable, no database required
  • Consequence: Does not support dynamic target discovery; requires config file changes to add/remove targets

• Multiple notification backends (Slack, email, HTTP webhooks)

  • Why: Flexibility to integrate with any alerting system
  • Consequence: Increased configuration complexity; each notifier requires separate credential management

• Real-time continuous monitoring (scan-based, not event-driven)
• Vulnerability remediation (scanning & reporting only, no patching automation)
• Windows system scanning (Linux/FreeBSD focused)
• Zero-trust network environments (requires SSH or API access to targets)
• Multi-tenant SaaS (designed for single organization deployments)

BoltDB cache persists in ./vuls/ by default; tests may fail if directory is read-only. Scan modes in config/scanmode.go are exclusive (only one active scan backend per run); misunderstanding this causes 'no vulnerabilities found' silently. Database freshness is critical: MaineK00n/vuls-data-update and trivy-db must be updated separately before scanning or CVE data will be stale. Network scanning (nmap) requires root or CAP_NET_RAW on Linux. No env var documentation visible; config is TOML/JSON-only. Docker image assumes /etc:/etc:ro mount for package database access on Linux; scans fail silently without it.

• Agent-less scanning — Core design principle of Vuls—understanding why it avoids deploying software on target hosts (reduces attack surface, simpler operations, no port management) explains architectural choices like SNMP for network devices and SSH-based remote execution
• Package metadata enumeration — Vuls detects vulnerabilities by reading installed package lists (APK, DEB, RPM) and version info, not by probing ports; understanding config/os.go and package manager abstraction is essential to extending OS support
• BoltDB (embedded key-value store) — Vuls uses BoltDB for local caching of scan results and vulnerability data; understanding cache/bolt.go is necessary for performance tuning and multi-host scan coordination
• Vulnerability database sources (NVD, JVN, Trivy DB) — Vuls combines multiple CVE feeds (NVD for US vulnerabilities, JVN for Japanese, Trivy DB for container-specific); data freshness and source reliability directly impact scan accuracy
• TOML configuration with schema validation — Config is loaded via BurntSushi/toml and validated with govalidator; understanding config/config.go is mandatory for debugging user configuration issues and extending supported settings
• Pluggable scan modules (scanmodule.go interface) — Architecture allows switching between OS package scanning, container scanning, and network scanning via config; this pattern enables extensibility without modifying core logic
• Software Bill of Materials (SBOM) integration (CycloneDX) — Vuls imports CycloneDX-go for SBOM parsing in CI/CD pipelines; understanding this integration is important for supply-chain security scanning and container image analysis

• aquasecurity/trivy — Vuls embeds Trivy (v0.69.2) for container and artifact scanning; understanding Trivy's database schema is essential for multi-scanner deployments
• MaineK00n/vuls-data-update — External module that populates the vulnerability database that Vuls scans against; required for fresh CVE data
• usiusi360/vulsrepo — Web UI frontend for Vuls reports (mentioned in README with demo GIF); common companion for visualization and historical tracking
• greenbone/openvas — Alternative agent-less vulnerability scanner for comparison; uses active scanning vs. Vuls' passive package-based approach
• anchore/grype — Similar vulnerability scanner for container images and SBOMs; often deployed alongside Vuls in multi-scanner security pipelines

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for config package modules

The config package is critical for Vuls (handling AWS, Azure, Slack, SMTP, etc. configurations), but most config files lack corresponding test files. Only config_test.go, os_test.go, portscan_test.go, tomlloader_test.go, and syslog/syslogconf_test.go exist. Missing tests for awsconf.go, azureconf.go, chatworkconf.go, googlechatconf.go, httpconf.go, saasconf.go, slackconf.go, smtpconf.go, telegramconf.go, and vulnDictConf.go would significantly improve reliability and catch regressions in notification/storage integrations.

• [ ] Create awsconf_test.go with tests for AWS credential validation and S3 configuration parsing
• [ ] Create azureconf_test.go testing Azure blob storage authentication and parameters
• [ ] Create slackconf_test.go, telegramconf_test.go, and other notification config tests validating webhook URLs and auth tokens
• [ ] Add tests for saasconf.go validating SaaS platform-specific config merging logic
• [ ] Run 'go test ./config/...' to ensure all tests pass and add to CI pipeline coverage requirements

Add integration tests for cache layer (bolt.go) with test fixtures

The cache package (cache/bolt.go, cache/db.go) is foundational for vulnerability data caching, but cache_test.go and bolt_test.go appear minimal. Add comprehensive tests covering cache miss/hit scenarios, concurrent access patterns, and BoltDB file corruption recovery. This is critical for a vulnerability scanner that needs reliable offline caching.

• [ ] Expand bolt_test.go with tests for concurrent read/write operations to cache/bolt.go
• [ ] Add test fixtures in cache/testdata/ directory with sample vulnerability datasets
• [ ] Create tests validating cache invalidation, TTL expiration, and recovery from corrupted BoltDB files
• [ ] Add benchmarks in cache/ to track performance regressions as vulnerability dataset sizes grow
• [ ] Document cache layer expectations in CONTRIBUTING.md or a new cache/README.md

Create missing CI workflow for diet/binary size checks and add goreleaser validation

The repo has diet-check.yml workflow but no validation that goreleaser.yml (.goreleaser.yml exists) actually builds successfully across all target platforms. The .goreleaser.yml config file exists but there's no CI step that validates the release artifacts or checks for binary bloat regressions. Adding this prevents broken releases and tracks binary size trends important for agent-less deployment.

• [ ] Create .github/workflows/goreleaser-validate.yml that runs 'goreleaser build --snapshot' on PRs to validate build configuration
• [ ] Extend diet-check.yml to compare binary sizes across releases and fail if any target platform binary grows >10% (configurable)
• [ ] Add build matrix in goreleaser-validate.yml for linux/amd64, linux/arm64, freebsd/amd64, and windows/amd64
• [ ] Document binary size expectations in CONTRIBUTING.md with links to .goreleaser.yml
• [ ] Reference the new workflow in .github/pull_request_template.md to remind contributors to check

• Add unit tests for config/color.go parsing; file exists but no color_test.go present, and config parsing logic should be fully covered
• Document the config/scanmodule.go plugin interface with an example walkthrough in CONTRIBUTING.md; new contributors struggle adding custom scan types without this
• Implement cache/bolt_test.go expansion to cover concurrent access and recovery scenarios; current test coverage appears minimal for embedded database reliability

• High · Outdated Alpine Base Image — Dockerfile (line 13). The Dockerfile uses Alpine 3.22 which may contain unpatched vulnerabilities. Alpine base images should be regularly updated to the latest stable version to receive security patches. Fix: Update to the latest stable Alpine version and rebuild regularly. Consider using Alpine 3.21 or later with automatic rebuilds in CI/CD.
• High · Missing SBOM and Dependency Verification — go.mod (dependencies section). The go.mod file contains numerous external dependencies without pinned versions (using version ranges or 'latest' semantics for some dependencies like vuls-data-update and vuls2). This increases the risk of supply chain attacks and unexpected behavior changes. Fix: Pin all dependencies to exact versions using checksums. Enable Go module verification with GOSUMDB or use go.sum validation in CI/CD pipeline.
• High · Hardcoded Email for Security Reports — SECURITY.md. Security vulnerability reports are directed to a single personal email (kotakanbe@gmail.com) without a formal security contact or disclosure policy. This lacks infrastructure for secure reporting and may delay vulnerability fixes. Fix: Establish a formal security.txt file at /.well-known/security.txt, use a dedicated security email address, and implement a vulnerability disclosure policy with expected response times.
• Medium · No Version Support Timeline — SECURITY.md. Security.md states 'Only the latest version is supported' which provides no clear support window or patching timeline for users running the tool in production environments. Fix: Define a clear versioning and support policy (e.g., support last 2-3 minor versions for 6 months). Implement automated security patching notifications.
• Medium · Dependency on Trivy with Transitive Dependencies — go.mod (aquasecurity packages). Heavy reliance on aquasecurity/trivy (v0.69.2) and trivy-db with multiple database dependencies creates a large attack surface through transitive dependencies. Fix: Regularly audit transitive dependencies using 'go mod graph' and 'go mod why'. Consider using tools like 'nancy' or 'snyk' in CI/CD for vulnerability scanning of dependencies.
• Medium · Insecure Default Configuration Pattern — config/ directory. Multiple configuration files (awsconf.go, azureconf.go, etc.) exist without visible validation shown. Risk of misconfiguration allowing credential exposure or insecure defaults. Fix: Implement strict validation for all configuration parameters. Use environment variables with validation, never accept sensitive data in config files. Document secure configuration practices.
• Medium · Missing Container Security Best Practices — Dockerfile. Dockerfile does not use specific golang version digest (uses :alpine without digest), runs apk add without --no-cache in some cases, and does not drop unnecessary capabilities or run as non-root user. Fix: Add digest to golang:alpine base image, ensure all RUN commands use --no-cache, add USER directive to run as non-root, and use COPY --chown for proper permissions.
• Low · Incomplete Dependency Version Pins — go.mod. Some dependencies use '+incompatible' or loose version specifications (e.g., github.com/cenkalti/backoff v2.2.1+incompatible), which may pull unexpected versions. Fix: Review and update incompatible dependencies to their v2+ versions where available. Use exact version pins with verification.
• Low · No Code Signing or Release Verification — .github/workflows/goreleaser.yml (implied). While goreleaser is configured, there is no visible implementation of binary signing or artifact verification for end-users. Fix: Implement GPG signing of releases in goreleaser configuration. Provide signed checksums and document verification process for users.
• Low · Broad SSH Access in Scanner Container — Dockerfile (openssh-client). Dockerfile includes openssh-client which may not be necessary for the scanning agent and increases potential attack surface. Fix: Evaluate

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.