Architecture

The VT ecosystem is split across four repositories that work together.

---

Repository Overview

Repo	Role
vt	Go CLI tool — the main user-facing binary
vt-templates	YAML template definitions + Docker Compose files
vt-site	Static website at vulnerabletarget.com
vt.wiki	This documentation

---

High-Level Data Flow

┌──────────────────────────────────────────────────────────┐
│                      vt-templates                        │
│  labs/ · cves/ · benchmarks/ · http/ · playbooks/       │
│  index.yaml + docker-compose.yaml per template           │
└────────────────────┬─────────────────────────────────────┘
                     │  git clone / git pull
                     ▼
┌──────────────────────────────────────────────────────────┐
│                     vt CLI                               │
│  - Loads templates from ~/vt-templates/                  │
│  - Manages state in ~/.vt-cli/                           │
│  - Delegates deployments to providers                    │
└───────────┬────────────────────────┬─────────────────────┘
            │ docker compose up/down  │ queries Docker API
            ▼                        ▼
┌────────────────────┐     ┌──────────────────────────────┐
│  Docker containers │     │  vt ps / vt inspect          │
│  (labeled with     │     │  (reads vt.template-id label)│
│   vt.template-id)  │     └──────────────────────────────┘
└────────────────────┘

                     GitHub Actions
                     │  generate templates.json
                     ▼
┌──────────────────────────────────────────────────────────┐
│                      vt-site                             │
│  vulnerabletarget.com — searchable catalog               │
└──────────────────────────────────────────────────────────┘

---

VT CLI Internal Structure

vt/
├── cmd/vt/
│   └── main.go               # Entry point, wires App and CLI
├── internal/
│   ├── app/                  # App struct (templates, playbooks, providers, config)
│   ├── cli/                  # Cobra command handlers
│   ├── banner/               # ASCII art banner with reticle pattern (Print + PrintAnimated)
│   ├── logger/               # zerolog wrapper
│   └── file/                 # File path utilities
└── pkg/
    ├── template/             # Template & playbook loading, parsing, validation
    │   ├── template.go
    │   ├── playbook.go
    │   ├── parser.go
    │   ├── loader.go         # Recursively walks vt-templates dir
    │   ├── downloader.go     # git clone / pull via go-git
    │   └── validator.go
    └── provider/
        ├── provider.go       # Provider interface: Start, Stop, Status, List
        ├── registry/         # Returns map of registered providers
        └── dockercompose/    # Docker Compose v2 implementation

Key Components

App container (internal/app)

Holds all runtime state:

• Templates map[string]template.Template
• Playbooks map[string]template.Playbook
• Providers map[string]provider.Provider
• Config *Config (template path, storage path, log level)

Provider interface (pkg/provider)

type Provider interface {
    Name() string
    Start(template *tmpl.Template) error
    Stop(template *tmpl.Template) error
    Status(template *tmpl.Template) (string, error)
    List() ([]ListDeployment, error)
}

Currently only docker-compose is implemented. The interface makes it straightforward to add Kubernetes or cloud providers later.

Template loader (pkg/template/loader.go)

• Clones vt-templates on first run if the local directory doesn't exist.
• Scans top-level category dirs (labs/, cves/, etc.), then recursively walks each with filepath.WalkDir looking for directories that contain an index.yaml.
• Playbooks are loaded from the playbooks/ dir as a special case; all other top-level dirs are treated as template categories.
• Enforces that a template's id field must match its directory name; duplicate IDs cause a load error.

Docker Compose provider (pkg/provider/dockercompose)

• Uses docker/compose v2 Go library directly (no shell-out).
• Injects vt.template-id (plus standard com.docker.compose.*) labels into every service at load time via loadComposeProject.
• List() discovers running deployments by listing all Docker Compose stacks whose project name starts with vt-, then reads the vt.template-id label from containers to get the canonical template ID.

---

Tech Stack

Layer	Technology
Language	Go 1.25.6 (as declared in go.mod)
CLI framework	Cobra v1.10.2
Logging	zerolog v1.34.0
Table output	go-pretty v6.7.8
YAML parsing	gopkg.in/yaml.v3
Git operations	go-git v5.17.0
Docker integration	docker/compose v2.40.3
Testing	testify v1.11.1

---

Default File Locations

Path	Purpose
~/vt-templates/	Local clone of the vt-templates repository
~/.vt-cli/	CLI state and storage

---

CI/CD

The main vt repo uses GitHub Actions for:

• Linting (golangci-lint)
• Tests (go test ./...)
• Build verification

The vt-templates repo uses GitHub Actions to:

• Generate templates.json (consumed by vt-site)
• Validate YAML against the schema

Pre-commit hooks enforce gofmt, yamllint, typos, and hadolint locally.