Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
// Package audit records audit events and their request metadata.
package audit
import (
"context"
"log/slog"
"net"
"net/http"
"time"
"github.com/bytebase/bytebase/backend/common"
"github.com/bytebase/bytebase/backend/common/log"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
)
// Audit method names for the two MCP doors that are not v1 RPCs. The
// interceptor names a row by the connect procedure it wrapped, so every
// consumer of AuditLog.method is shaped for "/<package>.<Service>/<Method>";
// these keep that shape without claiming a name in bytebase.v1, which is the
// surface the protos define and where the next reader would go looking for a
// descriptor. component/recovery already names its rows the same way, under
// bytebase.cli. The method part names what was ATTEMPTED — the row's status
// carries the verdict.
const (
// AuditMethodMCPSessionAuthorize is a bearer token presented at /mcp and
// held against the workspace ceiling. Per REQUEST, not per session: /mcp is
// Streamable HTTP, so a client polling a workspace that refuses it writes a
// row per poll. Nothing collapses repeats. Retention bounds the volume; if
// that stops being enough, collapse on the session fingerprint the
// middleware already computes for an admitted request.
AuditMethodMCPSessionAuthorize = "/bytebase.mcp.Session/Authorize"
// AuditMethodMCPConsentApprove is a user approving an MCP OAuth2 consent.
AuditMethodMCPConsentApprove = "/bytebase.mcp.Consent/Approve"
)
// LogWriter inserts one audit row. The v1 audit interceptor and the doors
// outside the connect chains write through it.
type LogWriter interface {
CreateAuditLog(ctx context.Context, workspace string, payload *storepb.AuditLog) error
}
// RecordOutOfBandAudit writes a row for a refusal no interceptor sees, and
// mirrors it to stdout when that is enabled.
//
// It stamps the severity itself. Every caller records a policy refusal, which
// the audit interceptor stamps WARNING when it makes the same call inside a
// connect chain, and a compliance reader filters on that field alone. Setting
// it here rather than at each door keeps a new door from answering INFO for a
// refusal the gate calls WARNING. A caller that needs to record something other
// than a refusal needs its own writer, not an argument here.
//
// Best effort by design: an audit row that cannot be written must never turn a
// refusal into an admission, so the caller gets no error to act on. The stdout
// mirror does NOT depend on the insert — a metadata-database failure is when
// losing the row from both surfaces would matter most.
func RecordOutOfBandAudit(ctx context.Context, writer LogWriter, mirrorToStdout bool, workspace string, row *storepb.AuditLog) {
row.Severity = storepb.AuditLog_WARNING
// WithoutCancel so the row survives a client hanging up on its own refusal,
// bounded because WithoutCancel drops the request deadline too. Every
// caller writes on the synchronous path of a refusal already decided, so an
// unbounded insert holds the user's answer open.
ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), outOfBandAuditTimeout)
defer cancel()
// Before the insert, not after: the stream is the surface that still works
// when the metadata database does not, so it must not queue behind it.
if mirrorToStdout {
LogAuditToStdout(ctx, row)
}
if err := writer.CreateAuditLog(ctx, workspace, row); err != nil {
slog.Warn("failed to record a policy denial",
slog.String("workspace", workspace), slog.String("method", row.GetMethod()), log.BBError(err))
}
}
// outOfBandAuditTimeout bounds a detached audit write. Long enough that an
// ordinary insert never trips it, short enough that a stalled metadata database
// delays a refusal by seconds rather than indefinitely.
const outOfBandAuditTimeout = 5 * time.Second
// maxAuditPayloadChars is the maximum characters for request/response payloads in stdout logs.
// Set to 100KB (102400 chars) to match AWS CloudTrail industry standard for audit logs.
const maxAuditPayloadChars = 102400
// LogAuditToStdout writes audit log events to stdout using Go's standard slog library.
// Output format is controlled by the global slog handler (JSON in production, text in dev).
// Logs include a "log_type": "audit" field to distinguish from application logs.
// This is a best-effort operation - errors are not returned to avoid failing the audit flow.
//
// Every writer in the server process calls this when stdout audit is enabled,
// so the stream carries every stored row. It also carries the v1 calls a
// permission check refused. The recovery CLI (component/recovery) is the
// exception — it writes without a profile to read the flag from.
func LogAuditToStdout(ctx context.Context, p *storepb.AuditLog) {
attrs := []slog.Attr{
slog.String("log_type", "audit"),
slog.String("parent", p.Parent),
slog.String("method", p.Method),
}
if p.Resource != "" {
attrs = append(attrs, slog.String("resource", p.Resource))
}
if p.User != "" {
attrs = append(attrs, slog.String("user", p.User))
}
if p.Status != nil {
attrs = append(attrs, slog.Int("status_code", int(p.Status.Code)))
if p.Status.Message != "" {
attrs = append(attrs, slog.String("status_message", p.Status.Message))
}
}
if p.Latency != nil {
attrs = append(attrs,
slog.Int64("latency_ms", p.Latency.AsDuration().Milliseconds()),
)
}
if p.RequestMetadata != nil {
if p.RequestMetadata.CallerIp != "" {
attrs = append(attrs, slog.String("client_ip", p.RequestMetadata.CallerIp))
}
if p.RequestMetadata.CallerSuppliedUserAgent != "" {
attrs = append(attrs, slog.String("user_agent", p.RequestMetadata.CallerSuppliedUserAgent))
}
}
// Include audit severity as an attribute (not as slog level)
// Audit logs are always logged at INFO level - they represent business events, not system health
// The severity field helps categorize the audit event itself
if p.Severity != storepb.AuditLog_SEVERITY_UNSPECIFIED {
attrs = append(attrs, slog.String("severity", p.Severity.String()))
}
attrs = append(attrs, mcpDelegationAttrs(p.McpDelegation)...)
// Include request payload (truncated to 100KB for log manageability)
// Request is already redacted for sensitive data by getRequestString()
if p.Request != "" {
request := p.Request
if truncated, wasTruncated := common.TruncateString(p.Request, maxAuditPayloadChars); wasTruncated {
request = truncated + "...[truncated]"
}
attrs = append(attrs, slog.String("request", request))
}
// Include response payload (truncated to 100KB for log manageability)
// Response is already redacted for sensitive data by getResponseString()
if p.Response != "" {
response := p.Response
if truncated, wasTruncated := common.TruncateString(p.Response, maxAuditPayloadChars); wasTruncated {
response = truncated + "...[truncated]"
}
attrs = append(attrs, slog.String("response", response))
}
slog.LogAttrs(ctx, slog.LevelInfo, p.Method, attrs...)
}
// mcpDelegationAttrs renders the MCP provenance for stdout audit lines:
// "mcp": true marks the row as MCP-originated even when the grant fields are
// empty (legacy sessions); the correlation ID is what operators pivot on to
// reassemble an agent session.
func mcpDelegationAttrs(d *storepb.MCPDelegation) []slog.Attr {
if d == nil {
return nil
}
attrs := []slog.Attr{
slog.Bool("mcp", true),
// Minted for every session, legacy included. Empty only on a consent
// entry, which never reached the /mcp boundary that mints it.
slog.String("mcp_correlation_id", d.CorrelationId),
}
if d.Scope != "" {
attrs = append(attrs, slog.String("mcp_scope", d.Scope))
}
if d.Resource != "" {
attrs = append(attrs, slog.String("mcp_resource", d.Resource))
}
if d.ClientId != "" {
attrs = append(attrs, slog.String("mcp_client_id", d.ClientId))
}
return attrs
}
// Caller-IP headers, in the precedence every audit path reads them: X-Real-IP
// is what a reverse proxy sets and is a single value, X-Forwarded-For is the
// standard one and can carry a client-supplied list. Both are
// client-controllable on a direct connection.
const (
HeaderRealIP = "X-Real-IP"
headerForwardedFor = "X-Forwarded-For"
)
// CallerIPFromHeaders reads the caller IP out of the forwarding headers, or ""
// when neither is set.
func CallerIPFromHeaders(header http.Header) string {
if ip := header.Get(HeaderRealIP); ip != "" {
return ip
}
return header.Get(headerForwardedFor)
}
// CallerIP resolves who made an HTTP request: the forwarding headers if
// present, otherwise the peer address.
func CallerIP(r *http.Request) string {
if ip := CallerIPFromHeaders(r.Header); ip != "" {
return ip
}
return StripPort(r.RemoteAddr)
}
// StripPort drops the port from a peer address so one audit column holds one
// shape. A forwarding header carries a bare IP; a peer address carries
// host:port, and storing both spellings of "who called" makes the column
// unusable for grouping.
func StripPort(addr string) string {
if host, _, err := net.SplitHostPort(addr); err == nil {
return host
}
return addr
}
// RequestMetadataFromHTTP renders the audit row's request metadata for a caller
// that arrived over plain HTTP rather than over a connect chain.
func RequestMetadataFromHTTP(r *http.Request) *storepb.RequestMetadata {
return &storepb.RequestMetadata{
CallerIp: CallerIP(r),
CallerSuppliedUserAgent: r.Header.Get("User-Agent"),
}
}