ghasetup

package
v3.84.13 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 2, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

Documentation

Overview

Package ghasetup wires third-party security scanners into a repository's GitHub Actions workflows.

The catalog is the single source of truth: `vulnetix gha setup` renders workflow jobs from it, and the published documentation examples are generated from it too. A tool documented on the website is therefore, by construction, the same job the command writes and the same job that runs in production.

Index

Constants

View Source
const WorkflowPath = ".github/workflows/vulnetix-scanners.yml"

WorkflowPath is the file `gha setup` manages, relative to the repository root.

It is deliberately separate from any hand-written workflow: the file is regenerated in full on every `gha setup`, so it must not be somewhere a user keeps their own jobs.

Variables

This section is empty.

Functions

func IsManaged

func IsManaged(content string) bool

IsManaged reports whether this file was written by `gha setup`.

func Render

func Render(c *Catalog, ids []string, opt Options) (string, error)

Render produces the complete workflow for the given tool ids.

The Vulnetix CLI is installed unpinned on purpose. install.sh resolves the latest release, so a workflow written today keeps working without anyone coming back to bump a version — which is exactly how a fleet ends up spread across three different CLI versions. Third-party scanners are pinned, because there the reproducibility of the scan matters more than being current.

func RepoRoot

func RepoRoot(dir string) (string, error)

RepoRoot returns the git working-tree root for dir.

func ToolsInWorkflow

func ToolsInWorkflow(c *Catalog, content string) []string

ToolsInWorkflow returns the catalog tool ids already wired into an existing managed workflow, so `gha setup` adds to the set rather than replacing it.

Types

type Catalog

type Catalog struct {
	Version int    `json:"version"`
	Tools   []Tool `json:"tools"`
}

Catalog is the parsed tool catalog.

func Load

func Load() (*Catalog, error)

Load parses the embedded catalog.

func (*Catalog) Find

func (c *Catalog) Find(id string) (*Tool, bool)

Find returns the tool with this id, matched case-insensitively.

func (*Catalog) IDs

func (c *Catalog) IDs() []string

IDs returns every tool id, sorted.

func (*Catalog) Suggest

func (c *Catalog) Suggest(id string) []string

Suggest returns catalog ids similar to the given one, for a "did you mean" on a typo or on a name the catalog spells differently ("trivy" is split into trivy-fs and trivy-config).

type Options

type Options struct {
	// SelfHostedLabels, when set, replaces `ubuntu-latest` on every job.
	SelfHostedLabels []string
	// OrgID is written into the publish job's env as a literal only when the
	// caller explicitly asks; otherwise the secret reference is used, which is
	// what almost every repository wants.
	OrgIDLiteral string
}

Options controls how the workflow is rendered.

type Remote

type Remote struct {
	// URL is the raw origin URL, empty when there is no origin.
	URL string
	// Host is the parsed host ("github.com", "gitlab.com", …), empty when the
	// URL could not be parsed.
	Host string
	// Slug is "owner/repo" when the URL could be parsed.
	Slug string
	// IsGitHub reports whether this is github.com or a GitHub Enterprise host.
	IsGitHub bool
}

Remote describes the repository's origin.

func DetectRemote

func DetectRemote(dir string) Remote

DetectRemote inspects the origin remote of the repository at dir.

A workflow file is only meaningful on GitHub, so the caller warns when this is something else. It is a warning rather than an error: mirrors, forks about to be pushed to GitHub, and Enterprise hosts with unusual names are all legitimate reasons to write the file anyway.

type Step

type Step struct {
	Name string            `json:"name,omitempty"`
	ID   string            `json:"id,omitempty"`
	Uses string            `json:"uses,omitempty"`
	Run  string            `json:"run,omitempty"`
	With map[string]any    `json:"with,omitempty"`
	Env  map[string]string `json:"env,omitempty"`
}

Step is one workflow step. Exactly one of Uses or Run is set.

type Tool

type Tool struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	JobName     string   `json:"jobName"`
	Category    string   `json:"category"`
	Description string   `json:"description"`
	Artifact    string   `json:"artifact"`
	Paths       []string `json:"paths"`
	Note        string   `json:"note,omitempty"`
	Steps       []Step   `json:"steps"`
}

Tool is one scanner: the job that runs it and the artifact it leaves behind.

Directories

Path Synopsis
Command ghasetupgen renders the third-party scanner documentation from the single source of truth: the embedded catalog (internal/ghasetup/catalog).
Command ghasetupgen renders the third-party scanner documentation from the single source of truth: the embedded catalog (internal/ghasetup/catalog).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL