Documentation
¶
Overview ¶
Package source fetches the code of a platform code scan: exactly one commit of one repository (ctis source.Repository), read-only, into a private directory a scanner then reads. It is the one fetch mechanism for every sensor and collector, so the hardening lives in one place.
The repository is untrusted. The fetch:
- speaks HTTPS only (every other git transport is off) to the host the platform named, pinned to an address the SSRF guard accepted (no DNS rebinding between the check and git's own lookup), without following redirects;
- runs no repository code: no hooks, no submodules, no filters (LFS, smudge/clean), no system or global git configuration;
- checks out symbolic links as plain files, so nothing in the checkout points outside it;
- verifies every object it receives (transfer.fsckObjects) and that the checkout is the requested commit;
- is bounded in time and in bytes on disk.
A credential (a short-lived token the platform minted for this one repository) reaches git only through its environment as an HTTP header scoped to the clone URL, never in argv (visible to every local user) or a file in the checkout, and never reaches a scanner.
Stability: Beta (docs/STABILITY.md).
Index ¶
Constants ¶
const ( DefaultTimeout = 10 * time.Minute DefaultMaxBytes = int64(2) << 30 // 2 GiB on disk )
Defaults.
Variables ¶
var ( // ErrTooLarge: the checkout grew past MaxBytes; the fetch was stopped. ErrTooLarge = errors.New("source: repository is larger than the fetch limit") // ErrHostRefused: the clone host resolves to an address the SSRF guard // refuses (or does not resolve). ErrHostRefused = errors.New("source: clone host refused") // ErrWrongCommit: the checkout is not the requested commit. ErrWrongCommit = errors.New("source: checkout is not the requested commit") )
Errors.
Functions ¶
This section is empty.
Types ¶
type Checkout ¶
type Checkout struct {
// Dir holds the working tree (and its .git directory).
Dir string
// Commit is the checked-out commit.
Commit string
// contains filtered or unexported fields
}
Checkout is a fetched commit.
type Credential ¶
Credential authenticates the fetch (HTTP basic). For a GitHub App installation token the username is "x-access-token"; for a GitLab token "oauth2".
type Fetcher ¶
type Fetcher struct {
// Root is the directory checkouts are created in (the sensor's scan
// workspace, so scanners may read them). Required.
Root string
// Git is the git binary; "" looks it up on PATH.
Git string
// Timeout bounds one fetch (DefaultTimeout when zero).
Timeout time.Duration
// MaxBytes bounds the checkout on disk (DefaultMaxBytes when zero).
MaxBytes int64
// AllowPrivate lets the clone host resolve to a private address
// (RFC 1918, ULA): an internal SCM reached by the tenant's own sensor.
// Loopback, link-local (cloud metadata), CGNAT and reserved ranges are
// always refused.
AllowPrivate bool
// Proxy, when set, is passed to git as its HTTPS proxy; the proxy then
// resolves the host and the address pin is not used.
Proxy string
// CAFile is a PEM bundle to trust for the SCM's certificate (an
// internal SCM with a private CA); "" uses the system roots.
CAFile string
// Resolve looks up the clone host (net.DefaultResolver when nil).
Resolve func(ctx context.Context, host string) ([]net.IP, error)
// contains filtered or unexported fields
}
Fetcher fetches repositories under Root.
func (*Fetcher) Fetch ¶
func (f *Fetcher) Fetch(ctx context.Context, repo ctissource.Repository, cred *Credential) (*Checkout, error)
Fetch validates repo, fetches exactly repo.Commit and checks it out. The caller removes the checkout when the scan is done.
Source Files