Documentation
¶
Overview ¶
Package privatekey is the provider for private keys committed as PEM blocks: SSH keys, the keys behind TLS certificates and other PKCS#8 or legacy PEM material, and the encrypted signing keys cosign writes.
None of them has an issuer to ask or an endpoint to revoke through. What makes such a leak matter is what the key opens, so the provider watches every scanned object for the public halves that name a key -- SSH public keys in authorized_keys, .pub files and Terraform or Ansible content, certificates, PUBLIC KEY blocks in cosign.pub and in the image policies that pin them -- and reports, per key, where its public half appears and what it protects. For SSH keys it also looks up the public keys GitHub publishes for the accounts that committed to the repository, so a key can be attributed to a login without ever being used; with --verify an unencrypted SSH key is offered to github.com once, which says whether any account or deploy key still accepts it.
The key material itself is kept only for that one verification and is never shown, fingerprinted or written to the JSON; every key is named by the fingerprint of its public half, or, for encrypted material whose public half cannot be derived, by a hash of the block.
Index ¶
- Constants
- func Identifiers(pub ssh.PublicKey) []string
- type Provider
- func (*Provider) Adjacent(kind detect.Kind, s detect.Sighting) []string
- func (*Provider) Classify(tok detect.Token, paths []string, matched []string) detect.Kind
- func (p *Provider) Committers(ctx context.Context, logins []string) map[string]string
- func (*Provider) Find(content []byte) []detect.Token
- func (*Provider) Identifiers(tok detect.Token) []string
- func (*Provider) Kinds() []detect.KindInfo
- func (*Provider) LocalSources() detect.LocalSources
- func (*Provider) Name() string
- func (*Provider) Observe(content []byte) []detect.Sighting
- func (*Provider) Revoke(context.Context, []detect.Token) error
- func (p *Provider) Verify(ctx context.Context, tok detect.Token) detect.Verification
Constants ¶
const ( // KindSSH is a private key in OpenSSH format, or a PEM key found where // SSH keys live; its name is the OpenSSH fingerprint of its public key // (`SHA256:…`) for the former, the SHA-256 of the SubjectPublicKeyInfo // for the latter. KindSSH detect.Kind = "ssh-private-key" // KindTLS is a PKCS#8, PKCS#1 or SEC1 PEM private key; its name is the // hex SHA-256 of its public key's SubjectPublicKeyInfo, or `sha256:` and // the hash of the block when the key is encrypted. KindTLS detect.Kind = "tls-private-key" // KindCosign is the encrypted signing key cosign writes; its name is // `sha256:` and the hash of the block, the public key not being // derivable. KindCosign detect.Kind = "cosign-private-key" )
Variables ¶
This section is empty.
Functions ¶
func Identifiers ¶
Identifiers returns the fingerprint forms a private key matching this public key is named by: the OpenSSH fingerprint and, for algorithms with a PKIX form, the SubjectPublicKeyInfo hash.
Types ¶
type Provider ¶
type Provider struct {
// KeysURL is where GitHub publishes the SSH public keys of an account
// as `<login>.keys`; https://github.com/ by default.
KeysURL string
// MetaURL is GitHub's meta endpoint, which publishes the fingerprints of
// its SSH host keys; https://api.github.com/meta by default. Empty
// skips the fetch and pins the embedded fingerprints.
MetaURL string
// SSHAddr is the SSH endpoint --verify offers keys to; github.com:22.
SSHAddr string
// HostKeys are the SHA256 fingerprints of the host keys SSHAddr may
// present; GitHub's published ones by default, replaced by what MetaURL
// says when it can be fetched. A server with any other key is refused.
HostKeys []string
// Client fetches .keys files and the meta endpoint.
Client *http.Client
// Timeout bounds the one SSH connection --verify makes per key.
Timeout time.Duration
// contains filtered or unexported fields
}
Provider implements detect.Provider, detect.CommitterCorrelator, detect.ProximityCorrelator and detect.PathClassifier for private keys.
func (*Provider) Adjacent ¶
Adjacent implements detect.ProximityCorrelator: a cosign key says nothing about its public half, so it adopts the PEM public key next to it, the cosign.pub `cosign generate-key-pair` writes beside cosign.key.
func (*Provider) Classify ¶
Classify implements detect.PathClassifier: a PEM key is an SSH key when it lives where SSH keys live (id_*, a .ssh directory) or when an SSH public key, in a file or on a GitHub account, names it; a key whose public half could not be read stays what its label made it.
func (*Provider) Committers ¶
Committers implements detect.CommitterCorrelator: the SSH public keys GitHub publishes for each login, under both fingerprint forms, each saying whose key it is. The .keys files are public and fetched without a token, once per login and run.
func (*Provider) Find ¶
Find implements detect.Provider: one substring pass for the armor header, then the block up to its matching end marker is parsed. A block that does not parse is not a key and is not reported.
func (*Provider) Identifiers ¶
Identifiers implements detect.Correlator: a key is known by its name.
func (*Provider) Kinds ¶
Kinds implements detect.Provider. Nothing here is revocable through an API; every kind carries the procedure that retires it.
func (*Provider) LocalSources ¶
func (*Provider) LocalSources() detect.LocalSources
LocalSources implements detect.Provider: the SSH directory, cosign's directory, and the variables CI jobs and cosign read keys from. Only fingerprints are compared; a variable that holds a path or a KMS URI instead of a key matches nothing.
func (*Provider) Observe ¶
Observe implements detect.Correlator. It returns the public halves an object names: SSH public keys on their own line (authorized_keys, .pub files) or inside a string (Terraform, Ansible, cloud-init), PUBLIC KEY blocks (cosign.pub, the keys an image policy pins), and certificates, each under the fingerprint forms a private key is named by. Anything else costs a few substring searches and returns nil.
func (*Provider) Revoke ¶
Revoke implements detect.Provider by refusing: there is no one to revoke a key with. The registry never gets here, no kind is revocable; the report carries the procedures instead.
func (*Provider) Verify ¶
Verify implements detect.Provider. An unencrypted SSH key is offered to the SSH endpoint once, as user git, with no command and no shell: the server either accepts the key, which means some account or deploy key still carries it, or refuses it, which means none does. The host key is checked against GitHub's published fingerprints first and any other server is refused. Encrypted keys, TLS keys and cosign keys have no one to ask; the matches line is their evidence.
Source Files