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 ¶
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 Render ¶
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 ToolsInWorkflow ¶
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 ¶
Catalog is the parsed tool catalog.
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 ¶
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). |