Inventory Linux packages over SSH, then match them against OSV.dev, Ubuntu USN, and local stub rules — from a single CLI.

BoxGuard targets Vagrant-managed machines (it reads vagrant ssh-config) or any host you can reach with SSH and a private key. Use it for quick security posture checks on dev boxes, CI images, or lab VMs.

• Features
• How it works
• Requirements
• Install
• Usage
• CLI reference
• Output
• Data sources
• Local test environment
• Project layout
• Security notes
• Development
• Contributing
• License

flowchart LR
  A[Vagrant or SSH config] --> B[SSH session]
  B --> C[OS + package inventory]
  C --> D[Hybrid matcher]
  D --> E[OSV.dev]
  D --> F[Ubuntu USN]
  D --> G[Stub rules]
  D --> H[Table or JSON report]

Each scan run uses a 2-minute overall timeout (see cmd/scan.go).

The bundled Vagrantfile uses the Docker provider and Ubuntu 18.04 for local CVE regression demos (pinned packages). Adjust for your environment.

git clone <repository-url> boxguard
cd boxguard
go mod tidy
go build -o boxguard .

Or use the Makefile:

make build    # produces ./boxguard
make test     # go test ./...

./boxguard scan --vagrant-path .

# Named machine (multi-machine Vagrantfile)
./boxguard scan --vagrant-path . --vagrant-machine web-server

./boxguard scan \
  --ssh-host 192.168.1.100 \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

# Non-default port
./boxguard scan --ssh-host 10.0.0.5 --ssh-user deploy --ssh-key ~/.ssh/id_ed25519 --ssh-port 2222

./boxguard scan --vagrant-path .              # table (default)
./boxguard scan --vagrant-path . -o json      # JSON

Global flags: -o, --output (table | json), -v, --verbose.

You must specify either Vagrant (--vagrant-path and/or --vagrant-machine) or --ssh-host with user and key.

OS: Ubuntu 18.04 LTS (ID=ubuntu, VERSION_ID=18.04)

+------+---------+-----------------+----------------------+-------------------+-----+--------+------+
| SEV  | PKG     | VERSION         | VULN                 | TITLE             | FIX | SOURCE | CVSS |
+------+---------+-----------------+----------------------+-------------------+-----+--------+------+
| HIGH | openssl | 1.1.0g-2ubuntu4 | CVE-2021-3711        | OpenSSL: SM2 decryption | 1.1.1l | osv    | 7.5  |
| HIGH | sudo    | 1.8.21p2-3      | CVE-2021-3156        | sudo: heap-based buffer overflow | 1.9.5p1 | osv    | 7.0  |
+------+---------+-----------------+----------------------+-------------------+-----+--------+------+

Packages: 171, Findings: 2
Stub findings: 0
OSV findings: 2

• OSV.dev — Aggregated advisories (CVE, GHSA, etc.) with CVSS where available.
• Ubuntu USN — RSS feed from Ubuntu security notices (used when ID=ubuntu in /etc/os-release).
• Stub database — Small in-repo rules for demonstration when live data does not apply.

Optional scripts for the Docker-based Ubuntu 18.04 box:

./test-cves.sh
./debug-scan.sh
vagrant destroy -f && vagrant up   # rebuild VM

cmd/              CLI (Cobra): root + scan
internal/util/    Version metadata
pkg/inventory/    OS detection, dpkg/rpm listing
pkg/model/        Shared structs
pkg/report/       Table and JSON reporters
pkg/sources/      Vagrant ssh-config + SSH runner
pkg/vuln/         Stub DB, OSV, USN, hybrid matcher

• SSH host keys are not verified by default (InsecureIgnoreHostKey in the SSH client). Use only in trusted networks or extend the client for host key pinning / known_hosts.
• Matching uses heuristics (package names, simple version compare). Treat output as indicative, not a substitute for full VM image scanning or distro security teams’ guidance.

Add a vulnerability source: implement logic under pkg/vuln/, then integrate with HybridMatcher in pkg/vuln/hybrid.go.

Add OS support: extend pkg/inventory/ for detection and package listing, and adjust OSV ecosystem mapping in pkg/vuln/osv.go if needed.

1. Fork the repo and create a branch (feature/… or fix/…).
2. Run make test (or go test ./...).
3. Open a Pull Request with a clear description of behavior changes.

Released under the MIT License.