go-security
Use when writing or reviewing Go code that touches untrusted input, secrets, or credentials — SQL, shell, or template injection, path traversal, SSRF, cookies and security headers, password hashing, TLS settings, token comparison, or what may appear in a log line. Also use when a handler accepts a file name, URL, or command argument from a client, or when asked to find "vulnerabilities", even if the user never says "security". Does not cover the os.Root and crypto/rand mechanics (see go-defensive) or the dependency CVE scan in the gate (see go-linting).
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 7
- Forks
- 2
01 前言 Front Matter
- name
- go-security
- description
- Use when writing or reviewing Go code that touches untrusted input, secrets, or credentials — SQL, shell, or template injection, path traversal, SSRF, cookies and security headers, password hashing, TLS settings, token comparison, or what may appear in a log line. Also use when a handler accepts a file name, URL, or command argument from a client, or when asked to find "vulnerabilities", even if the user never says "security". Does not cover the os.Root and crypto/rand mechanics (see go-defensive) or the dependency CVE scan in the gate (see go-linting).
02 资源文件 4
- 参考文档references/ACCESS-CONTROL.md12.0 KB
- 参考文档references/INJECTION.md13.8 KB
- 参考文档references/REVIEW.md3.4 KB
- 参考文档references/SECRETS-AND-CRYPTO.md13.5 KB
03 SKILL.md 正文
Go Security
Compatibility: Baseline Go 1.27 (see COMPATIBILITY.md).
os.Rootandcrypto/pbkdf2,crypto/hkdf,crypto/sha3are Go 1.24+;http.NewCrossOriginProtectionGo 1.25+;crypto/subtle,html/template, andnet/netipare long-standing stdlib.
A vulnerability is a trust boundary nobody named. Before writing or reviewing, answer three questions: where does untrusted data enter, which sensitive operation does it reach (query, shell, file path, URL fetch, HTML, log), and what is the blast radius if the defense fails. Every rule below is one of those paths, with the standard-library defense that closes it.
Resource Routing
references/INJECTION.md- Read when untrusted data reaches SQL,os/exec, a template or a template's source, a file path, an outbound URL, a redirect, or a decompressor, or is served back as a download.references/SECRETS-AND-CRYPTO.md- Read when handling passwords, a login or reset flow, tokens, API keys, webhook signatures, TLS configuration, or choosing a hash or cipher.references/ACCESS-CONTROL.md- Read when code decides who may act: auth middleware and route registration, the tenant a query uses, batch, export, import, or background jobs, a cache, model tool calls, mTLS, gRPC, or queue identity, an OAuth login, or CORS with credentials.references/REVIEW.md- Read when asked to audit or find vulnerabilities, or when writing up and ranking a security finding inside a review.
Quick Reference
| Threat | Defense | Caught by |
|---|---|---|
| SQL injection | QueryContext(ctx, q, args...) placeholders; identifiers from a switch over known names |
gosec G201/G202, and G701 for a request value in the query text |
| Foreign row by ID | AND org_id = the caller's tenant, a parameter beside the ID (INJECTION.md); a foreign ID is sql.ErrNoRows |
review |
| Tenant from the client | The tenant the middleware checked is the one the query uses; no OrgID in the request type (ACCESS-CONTROL.md) |
review |
| Route outside the auth wrapper | Wrap the whole mux once and list the public patterns in the wrapper (ACCESS-CONTROL.md) | review |
| Auth that fails open | Every branch answers and returns: a store or verifier error is 503, never anonymous; an empty allowlist denies |
review |
| Batch, export, import, background job | Authorize each item as the requesting principal when the effect happens (ACCESS-CONTROL.md) | review |
| Cache shared across tenants | The tenant in the key: struct{ org, id string }, not the ID alone |
review |
| Quota, balance, or one-time code checked then spent | One conditional UPDATE … WHERE or a locked row (go-database) |
review — -race sees no race between two transactions |
| Model output, tool-call arguments | Untrusted input; the tool handler authorizes as the user the agent acts for (ACCESS-CONTROL.md) | review |
| Command injection | exec.CommandContext(ctx, "gzip", "--keep", "--", name): argv, no shell, -- before input |
gosec G204, which fires on this safe form too: suppress it on that line with the reason, as in Injection |
| XSS | html/template (contextual escaping) |
gosec G203 (unsafe template.HTML), G705 (a request value written to the response) |
| Template written by a client | Never Parse client text: it calls any exported method on the data; fixed placeholders (INJECTION.md) |
review — gosec G708 sees a request value in text/template's Parse only, not html/template's |
| Path traversal | root.Open(name) on an os.Root opened once at startup (go-defensive owns the form) |
review — gosec G703 reports a request value in os.Open and passes root.Open; G304 fires on every variable path, so the bundled config excludes it |
| Upload served inline | Content-Disposition: attachment, X-Content-Type-Options: nosniff, a Content-Type you derived; or a separate origin |
review |
| SSRF | Hostname allowlist by whole label: host == d or strings.HasSuffix(host, "."+d), re-checked on every redirect in CheckRedirect; else a net.Dialer.Control that rejects, on the dialed address, netip.Addr.IsPrivate()/loopback and the CGNAT and NAT64 prefixes those methods miss (INJECTION.md) |
review — gosec G704 reports the request either way (below) |
| Decompression bomb | io.LimitReader on the gzip.Reader, not only MaxBytesReader on the body; the same cap on a fetched response body |
review — gosec G110 sees io.Copy from the reader, not io.ReadAll |
| Duration or count from input | Parse, then clamp to a server [min, max]; 0 and huge are both attacks | review |
| Open redirect | One leading /; reject //, \, and control characters; or an allowlist of hosts |
review — gosec G710 reports the redirect either way (below) |
| Predictable tokens | crypto/rand.Text() / rand.Read |
gosec G404 |
| Timing leak on compare | subtle.ConstantTimeCompare(a, b) == 1 |
review |
| Webhook signature | HMAC over the raw body bytes and the signed timestamp, hmac.Equal, a tolerance window, decode only after (SECRETS-AND-CRYPTO.md) |
review |
| Account enumeration at login | A dummy hash for an unknown user, one error for both failures, a semaphore on concurrent hashes (SECRETS-AND-CRYPTO.md) | review |
| Weak password hash | argon2id (or crypto/pbkdf2 when stdlib-only) |
review — G401 and the G501/G505 import blocklists catch MD5/SHA1 only, not sha256.Sum256(password) |
InsecureSkipVerify: true |
Never outside a test against a local self-signed server; RootCAs for a private CA |
gosec G402 |
MinVersion |
Leave unset (1.2 is the default) unless the service is TLS 1.3-only | gosec G402 |
CurvePreferences |
No list: the default has X25519MLKEM768, SecP256r1MLKEM768, and SecP384r1MLKEM1024. A list that omits any is a finding, fixed by deleting it, not reordering it (order is ignored); only opt-in MLKEM1024 needs a list (SECRETS-AND-CRYPTO.md) |
review |
| CSRF | http.NewCrossOriginProtection().Handler(mux) |
review |
| CORS with credentials | Exact-origin allowlist, Vary: Origin; the same list in AddTrustedOrigin (HTTP Surface) |
review |
Secret in a log, fmt, or JSON |
The secret type in go-logging, which covers an exported struct field; a struct with the secret in an unexported field prints itself without it (same section) | review |
| Detail returned in an error | Status + generic text; detail stays server-side | review |
| Known CVE in deps | govulncheck ./... (gate) |
gate |
Apply a row's defense at the boundary, once — not at every call site downstream, where it is forgotten.
gosec is in the baseline .golangci.yml; a finding it raises is a gate
failure, not advice. See go-linting. A row marked
review has no tool, or a tool that sees one shape of it; a clean gosec
run does not clear it.
A taint finding on a defended line
gosec's taint rules (G701–G710) follow a request value to a sink and cannot
see the check in between: G704 reports a client URL fetched after the
allowlist or through publicClient, G710 a redirect after localRedirect,
and G120 a ParseMultipartForm under MaxBytesReader. Once the defense is
in the code, suppress on the reported line with that defense as the reason —
a fragment of three handlers; never suppress first and defend later:
req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil) //nolint:gosec // G704: client dials through a Control that rejects private ranges
resp, err := client.Do(req) //nolint:gosec // G704: the same client
http.Redirect(w, r, next, http.StatusSeeOther) //nolint:gosec // G710: next passed localRedirect
err := r.ParseMultipartForm(1 << 20) //nolint:gosec // G120: body capped by MaxBytesReader above
Injection
The defense is always the same shape: hand data to an API that knows it is data. String assembly is what turns data into code.
// ✗ Bad — the shell re-parses ref; "main; rm -rf /" is one argument to sh
out, err := exec.Command("sh", "-c", "git log "+ref).Output()
// ✓ Good — argv, no shell; option parsing ends before ref, so "--output=x" stays a revision
out, err := exec.CommandContext(ctx, "git", "log", "--end-of-options", ref, "--").Output() //nolint:gosec // G204: fixed program, argv, options end before ref
--end-of-options is git's spelling, because -- already separates
revisions from paths there; every other program takes -- before the first
argument built from input, as in the Quick Reference row.
Secrets
- Read secrets from the environment or a mounted file at startup; never from a literal, a flag default, or a committed config. Fail fast when missing.
- Verify a signed token the client presents (JWT, a signed cookie) with a
fixed algorithm allowlist and keys you already hold:
kidonly chooses among those keys, andalg,jku, orx5uinside the token never choose either. Reject a token withoutexp, checkexpagainst the server clock, and checkissandaudagainst fixed values. - Keep secrets out of errors: never
fmt.Errorf("auth %s: %w", token, err).
Key derivation, TLS defaults, and cookie flags in SECRETS-AND-CRYPTO.md.
HTTP Surface
go-http owns the server construction; the security
items it carries are ReadHeaderTimeout, MaxBytesReader on every decoded
body, MaxHeaderValueCount, and http.NewCrossOriginProtection. Add here:
http.SetCookie(w, &http.Cookie{
Name: "__Host-session", Value: id, // the prefix: browsers enforce Secure, Path=/, no Domain
HttpOnly: true, Secure: true, SameSite: http.SameSiteLaxMode,
Path: "/", MaxAge: 3600,
})
gosec G124 reports a cookie missing any of Secure, HttpOnly, or
SameSite.
CORS relaxes the same-origin policy, so the allowlist is the whole defense:
exact origins, never a reflected Origin or "null" beside
Allow-Credentials, and the same list trusted in CrossOriginProtection
(ACCESS-CONTROL.md has
the middleware).
net/http/pprofandexpvarregister onhttp.DefaultServeMuxininit, so one blank import anywhere in the binary publishes them on every server whoseHandleris nil. Serve the public listener from your own mux and mount the debug handlers on a separate internal listener — they leak heap contents and goroutine stacks.gosecG108 reports thepprofblank import wherever it is, the internal listener included: suppress it there with the listener as the reason.X-Forwarded-Foris client-writable and append-only: join everyr.Header.Values("X-Forwarded-For")line and take the rightmost entry that is not one of your own proxies;r.Header.Getreturns only the first line, which the client wrote when a proxy adds its own. With no proxy in front,r.RemoteAddr.
Review Mode
An audit traces data flow from every input to its first sink, checks every
Quick Reference row marked review, and ranks each finding critical to low by
what the evidence shows: REVIEW.md.
Related Skills
- go-database: placeholder queries, identifier allowlists.
- go-logging:
LogValuerand what never reaches a log line. - go-resilience: rate limits, duplicate delivery, and idempotency keys.
- go-troubleshooting: a crash or hang rather than a known vulnerability.
04 同仓库更多 Skills
go-troubleshooting
Use when investigating a bug or ticket in a Go service whose cause is unknown — wrong or missing results, tenant-specific behavior, a regression, stage/prod/CI differences, a panic, hang, deadlock, leak, unexplained CPU/RSS growth, or a flaky test. Also use for pasted stack traces, profiles, logs, or requests to find a Go issue's root cause, even without the word debug. Does not cover rewriting ticket text, implementing an already-diagnosed fix alone (use its topic skill), or optimizing a known bottleneck (see go-performance).
go-testing
Use when writing, reviewing, or improving Go test code — including table-driven tests, subtests, parallel tests, test helpers, test doubles, and assertions with cmp.Diff. Also use when a user asks to write a test for a Go function, even if they don't mention specific patterns like table-driven tests or subtests. Does not cover benchmark performance testing (see go-performance).
go-style-core
Use when resolving Go style or language mechanics such as formatting, nesting, declarations, initialization, scope, shadowing, loops, switches, or enum zero values. API design, naming, errors, and tests have specialized skills.
go-resilience
Use when handling Go dependency failures or overload with retries, backoff/jitter, budgets, idempotency, duplicate delivery, circuit breakers, bulkheads, rate limits, backpressure, or degradation. Unknown root causes belong to go-troubleshooting.
go-performance
Use when optimizing slow or performance-critical Go code, allocations, string concatenation in loops, or benchmarks. Also use when writing or reviewing a cache, including implementing one from a stub — its key, its expiry, and how a miss loads. Concurrent code patterns belong to go-concurrency.
go-packages
Use when creating or splitting Go packages, organizing imports or dependencies, or structuring a new Go project. Individual identifier naming belongs to go-naming.