deltascope

package
v0.400.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

README

Public Package Module

Stable public package surface for library consumers.

Files

File Responsibility
doc.go Declares the public package placeholder
audit.go Exposes the stable public audit API, optional metadata-provider hooks, and public result/request types
query_access.go Exposes the stable public query access analysis API, schema resolver interface, and public result/request types
query_access_session.go Exposes the opaque PostgreSQL session wrapper for trusted query access (postgresql build tag)
query_access_session_stub.go Provides PostgreSQL session stub when built without postgresql tag
version.go Publishes the default semantic version and canonical ASCII logo
audit_test.go Verifies the public audit API with defaults, overrides, multi-statement input, PostgreSQL request routing, and metadata-aware request plumbing
query_access_test.go Verifies the public query access API with dialect routing, mode handling, JSON structure parity, and context cancellation

Exports

  • Audit(ctx, request)
  • Request
  • MetadataProvider
  • Metadata
  • InstanceFacts
  • TableSnapshot
  • Table
  • Column
  • Index
  • Constraint
  • Result
  • StatementResult
  • Explanation
  • Finding
  • FindingExplanation
  • ExplanationMetadata
  • Level Public finding level type for blocker, warning, and notice
  • Summary
  • Location
  • Dialect Includes DialectPostgreSQL for PostgreSQL request routing support
  • Verdict
  • DefaultVersion
  • Logo
  • AnalyzeQueryAccess(ctx, request) Performs query access analysis and returns read classification, admission, and permission requirements
  • QueryAccessRequest Input for query access analysis with SQL, dialect, mode, default schema, and optional schema resolver
  • QueryAccessResult Output of query access analysis with structured JSON fields for dialect, mode, classification, admission, relations, columns, outputs, requirements, unresolved references, and warnings
  • QueryAccessMode Controls which column references become requirements: strict or projection_only
  • QueryAccessReadClassification Describes whether SQL is read-only: read_only, not_read_only, or indeterminate
  • QueryAccessAdmission Describes whether SQL is eligible for authorization: admissible, rejected, or indeterminate
  • QueryAccessSchemaResolver Optional interface for resolving relation metadata during analysis
  • QueryAccessRelationReference Relation reference with Unbound field marking relations that must not produce physical requirements
  • QueryAccessColumnReference Column reference with Unbound field indicating the column could not be resolved to a qualified schema.table.column
  • PostgreSQLQueryAccessSession Opaque wrapper for a caller-owned *sql.Conn for trusted PostgreSQL query access analysis (postgresql build tag only)
  • NewPostgreSQLQueryAccessSessionFromConn(ctx, conn) Creates an opaque session from a caller-owned *sql.Conn with context for liveness check; the session does not close the connection (postgresql build tag; stub returns ErrPostgreSQLSessionNotAvailable in non-postgresql builds)
  • AnalyzePostgreSQLQueryAccessWithSession(ctx, session, req) Performs trusted PostgreSQL query access analysis using a caller-owned connection session; may return read_only + admissible when all effects are manifest-proven (postgresql build tag; stub returns ErrPostgreSQLSessionNotAvailable in non-postgresql builds)

Notes

  • Request now carries top-level Schema and MetadataProvider fields so CLI, HTTP, and library consumers can opt into metadata-aware audits without changing the offline call shape.
  • Public MetadataProvider stays minimal; standalone PostgreSQL index-owner resolution remains an internal optional seam behind the application metadata enrichment layer.
  • Result and StatementResult expose an optional Explanation field for additive shared result context without changing verdict semantics. The built-in audit flow populates these aggregate fields whenever findings are present.
  • Result now also exposes Unsupported ([]spec.UnsupportedDetail) and Diagnostics ([]spec.Diagnostic) arrays so library consumers can inspect structured partial-support and parser-error/unsupported-statement outcomes.
  • ErrUnsupportedStatement is returned when unsupported statements are present, while still returning a populated Result for supported statements.
  • Finding now exposes an optional Explanation field so library consumers can read structured per-finding why, risk, suggestion, and metadata-status notes directly.
  • DefaultVersion is v0.400.0, matching the current repository release baseline for source builds.
  • Release surface gates verify that DefaultVersion stays aligned with the release tag so source-built binaries do not drift behind published artifacts.

Dependencies

  • Upstream: external library consumers
  • Downstream: context, internal/application/audit, internal/application/queryaccess, internal/domain/queryaccess, internal/domain/report, internal/domain/rule, internal/domain/spec

Update Rule

  • If members/interfaces/dependencies change, update this file in same change.

Documentation

Overview

Package deltascope exposes the public library surface for consumers. input: public audit requests carrying SQL text, dialect, optional config path, and optional metadata providers output: stable audit results for embedding DeltaScope in tools and agents pos: public audit API above the internal application service note: if this file changes, update this header and module README.md.

Package deltascope exposes the public library surface for consumers. input: external library calls into the DeltaScope audit engine output: stable exported API for embedding DeltaScope pos: public package boundary above internal application services note: if this file changes, update this header and module README.md.

Package deltascope exposes the public library surface for consumers. input: public query access requests carrying SQL text, dialect, mode, and optional schema resolver output: stable query access analysis results for embedding DeltaScope in tools and agents pos: public query access API above the internal application service note: if this file changes, update this header and module README.md.

Defense in Depth: Query access analysis is one layer in a defense-in-depth authorization strategy. It supplements, but does not replace, database authorization, grant evaluation, row-level security, and audit logging. Always pair this analysis with proper authentication and authorization checks.

Package deltascope exposes the public library surface for consumers. input: caller-owned *sql.Conn for PostgreSQL trusted query access output: shared types and errors for session API across build tags pos: public shared session types (no build tag) note: if this file changes, update this header and module README.md.

Package deltascope provides the PostgreSQL session stub when built without the postgresql tag. input: none (stub only) output: ErrPostgreSQLSessionNotAvailable for all calls pos: public stub for non-PostgreSQL builds note: if this file changes, update this header and module README.md.

Package deltascope exposes the stable public audit API. input: build metadata consumers and public version/logo queries output: shared default version and ASCII logo values for CLIs and services pos: public package metadata alongside the stable audit entrypoint note: if this file changes, update this header and module README.md.

Index

Constants

View Source 
const (
	ImpactSourceShape    ImpactSource = "shape"
	ImpactSourceMetadata ImpactSource = "metadata"
	ImpactSourcePlan     ImpactSource = "plan"

	ImpactRiskLow     ImpactRisk = "low"
	ImpactRiskMedium  ImpactRisk = "medium"
	ImpactRiskHigh    ImpactRisk = "high"
	ImpactRiskUnknown ImpactRisk = "unknown"

	ImpactConfidenceLow    ImpactConfidence = "low"
	ImpactConfidenceMedium ImpactConfidence = "medium"
	ImpactConfidenceHigh   ImpactConfidence = "high"
)
View Source 
const (
	// DefaultVersion is the repository's current default semantic version.
	DefaultVersion = "v0.400.0"

	Logo = "    ____       ____        _____                     \n" +
		"   / __ \\___  / / /_____ _/ ___/_________  ____  ___ \n" +
		"  / / / / _ \\/ / __/ __ `/\\__ \\/ ___/ __ \\/ __ \\/ _ \\\n" +
		" / /_/ /  __/ / /_/ /_/ /___/ / /__/ /_/ / /_/ /  __/\n" +
		"/_____/\\___/_/\\__/\\__,_//____/\\___/\\____/ .___/\\___/ \n" +
		"                                       /_/           "
)

Variables

View Source 
var ErrInvalidQueryAccessMode = errors.New("invalid query access mode: must be strict or projection_only")

ErrInvalidQueryAccessMode is returned when the mode is not a recognized value.

View Source 
var ErrPostgreSQLSessionNotAvailable = errors.New("postgresql session support requires build tag: go build -tags postgresql")

ErrPostgreSQLSessionNotAvailable indicates PostgreSQL session support was not compiled in. This error is returned by the stub constructor when built without the postgresql tag.

View Source 
var ErrQueryAccessUnsupportedDialect = errors.New("unsupported dialect for query access analysis")

ErrQueryAccessUnsupportedDialect is returned when the dialect is not supported for query access analysis.

View Source 
var ErrUnsupportedStatement = errors.New("deltascope audit includes unsupported statements")

Functions

This section is empty.

Types

type Column 

type Column = spec.Column

Column mirrors the domain column shape used inside metadata snapshots.

type Constraint 

type Constraint = spec.Constraint

Constraint mirrors the domain constraint shape used inside metadata snapshots.

type Dialect 

type Dialect string

Dialect identifies the SQL dialect for public callers. 

const (
	DialectMySQL      Dialect = "mysql"
	DialectTiDB       Dialect = "tidb"
	DialectPostgreSQL Dialect = "postgresql"
)

type Explanation added in v0.6.2 

type Explanation struct {
	Summary string   `json:"summary,omitempty"`
	Reasons []string `json:"reasons,omitempty"`
}

Explanation is the stable public result-level explanation shape.

type ExplanationMetadata added in v0.6.2 

type ExplanationMetadata struct {
	Status string `json:"status,omitempty"`
	Note   string `json:"note,omitempty"`
}

ExplanationMetadata describes how metadata availability affected a public finding explanation.

type Finding 

type Finding struct {
	RuleID         string              `json:"rule_id"`
	Level          Level               `json:"level"`
	Message        string              `json:"message"`
	StatementIndex int                 `json:"statement_index,omitempty"`
	StatementKind  string              `json:"statement_kind,omitempty"`
	Location       *Location           `json:"location,omitempty"`
	Suggestion     string              `json:"suggestion,omitempty"`
	Metadata       map[string]any      `json:"metadata,omitempty"`
	Explanation    *FindingExplanation `json:"explanation,omitempty"`
}

Finding is the stable public finding shape.

type FindingExplanation added in v0.6.2 

type FindingExplanation struct {
	Summary    string               `json:"summary,omitempty"`
	Why        string               `json:"why,omitempty"`
	Risk       string               `json:"risk,omitempty"`
	Suggestion string               `json:"suggestion,omitempty"`
	Metadata   *ExplanationMetadata `json:"metadata,omitempty"`
}

FindingExplanation is the stable public per-finding explanation shape.

type Impact added in v0.14.0 

type Impact struct {
	EstimatedRows  *int64           `json:"estimated_rows,omitempty"`
	EstimatedRatio *float64         `json:"estimated_ratio,omitempty"`
	RiskLevel      ImpactRisk       `json:"risk_level,omitempty"`
	Confidence     ImpactConfidence `json:"confidence,omitempty"`
	Source         ImpactSource     `json:"source,omitempty"`
	ReasonCodes    []string         `json:"reason_codes,omitempty"`
	Notes          []string         `json:"notes,omitempty"`
}

Impact is the stable public statement-level DML impact estimate shape.

type ImpactConfidence added in v0.14.0 

type ImpactConfidence string

ImpactConfidence identifies the public estimate-confidence bucket.

type ImpactRisk added in v0.14.0 

type ImpactRisk string

ImpactRisk identifies the public conservative risk bucket for a DML statement.

type ImpactSource added in v0.14.0 

type ImpactSource string

ImpactSource identifies the public origin of a statement-level DML impact estimate.

type Index 

type Index = spec.Index

Index mirrors the domain index shape used inside metadata snapshots.

type InstanceFacts 

type InstanceFacts = spec.InstanceFacts

InstanceFacts mirror metadata-aware instance facts for public providers.

type Level 

type Level string

Level identifies the public finding severity. 

const (
	LevelBlocker Level = "blocker"
	LevelWarning Level = "warning"
	LevelNotice  Level = "notice"
)

type Location 

type Location struct {
	Line   int `json:"line,omitempty"`
	Column int `json:"column,omitempty"`
}

Location identifies a public source span when available.

type Metadata 

type Metadata = spec.Metadata

Metadata mirrors the optional domain metadata facts exposed on statements.

type MetadataProvider 

type MetadataProvider interface {
	LoadInstanceFacts(ctx context.Context, dialect Dialect, schema string) (*InstanceFacts, error)
	LoadTableSnapshot(ctx context.Context, dialect Dialect, schema string, table string) (*TableSnapshot, error)
}

MetadataProvider supplies optional metadata-aware facts for one public audit request.

type PlanEstimateProvider added in v0.18.0 

type PlanEstimateProvider interface {
	LoadPlanEstimate(ctx context.Context, statement spec.Statement) (*spec.ImpactEstimate, error)
}

PlanEstimateProvider optionally supplies planner-backed DML impact estimates.

type PostgreSQLQueryAccessSession added in v0.390.0 

type PostgreSQLQueryAccessSession struct {
	// contains filtered or unexported fields
}

PostgreSQLQueryAccessSession is an opaque wrapper around a caller-owned *sql.Conn for trusted PostgreSQL query access analysis.

The session does not own or close the caller's connection. The caller retains full lifecycle control. Analysis on an already-closed connection returns a bounded error.

The wrapper exposes no OIDs, manifest entries, catalog SQL, credentials, session binding, or Trusted flag. It has no JSON-marshalable fields.

func NewPostgreSQLQueryAccessSessionFromConn added in v0.390.0 

func NewPostgreSQLQueryAccessSessionFromConn(_ context.Context, _ *sql.Conn) (*PostgreSQLQueryAccessSession, error)

NewPostgreSQLQueryAccessSessionFromConn returns ErrPostgreSQLSessionNotAvailable when built without the postgresql tag.

type QueryAccessAdmission added in v0.380.0 

type QueryAccessAdmission string

QueryAccessAdmission describes whether SQL is eligible for caller authorization. 

const (
	// QueryAccessAdmissible indicates the statement is eligible for authorization checks.
	QueryAccessAdmissible QueryAccessAdmission = "admissible"
	// QueryAccessRejected indicates the statement is not eligible for authorization checks.
	QueryAccessRejected QueryAccessAdmission = "rejected"
	// QueryAccessIndeterminateAdmission indicates the admission status could not be determined.
	QueryAccessIndeterminateAdmission QueryAccessAdmission = "indeterminate"
)

type QueryAccessColumnReference added in v0.380.0 

type QueryAccessColumnReference struct {
	Schema  string   `json:"schema,omitempty"`
	Table   string   `json:"table"`
	Column  string   `json:"column"`
	Usages  []string `json:"usages"`
	Unbound bool     `json:"unbound,omitempty"`
}

QueryAccessColumnReference represents a source column reference.

type QueryAccessColumnSchema added in v0.380.0 

type QueryAccessColumnSchema struct {
	Name    string
	Ordinal int
}

QueryAccessColumnSchema contains metadata about a column.

type QueryAccessMode added in v0.380.0 

type QueryAccessMode string

QueryAccessMode controls which column references become requirements. 

const (
	// QueryAccessModeStrict requires all referenced columns to be authorized.
	QueryAccessModeStrict QueryAccessMode = "strict"
	// QueryAccessModeProjectionOnly requires only projected columns to be authorized.
	QueryAccessModeProjectionOnly QueryAccessMode = "projection_only"
)

type QueryAccessOutputColumn added in v0.380.0 

type QueryAccessOutputColumn struct {
	Name    string   `json:"name"`
	Sources []string `json:"sources"`
}

QueryAccessOutputColumn represents a final output column.

type QueryAccessReadClassification added in v0.380.0 

type QueryAccessReadClassification string

QueryAccessReadClassification describes whether SQL is demonstrably read-only. 

const (
	// QueryAccessReadOnly indicates the statement contains no write operations.
	QueryAccessReadOnly QueryAccessReadClassification = "read_only"
	// QueryAccessNotReadOnly indicates the statement contains at least one write operation.
	QueryAccessNotReadOnly QueryAccessReadClassification = "not_read_only"
	// QueryAccessIndeterminate indicates the read-only status could not be determined.
	QueryAccessIndeterminate QueryAccessReadClassification = "indeterminate"
)

type QueryAccessRelationKind added in v0.380.0 

type QueryAccessRelationKind string

QueryAccessRelationKind describes the type of relation reference. 

const (
	// QueryAccessRelationTable indicates a base table reference.
	QueryAccessRelationTable QueryAccessRelationKind = "table"
	// QueryAccessRelationView indicates a view reference.
	QueryAccessRelationView QueryAccessRelationKind = "view"
	// QueryAccessRelationCTE indicates a common table expression reference.
	QueryAccessRelationCTE QueryAccessRelationKind = "cte"
	// QueryAccessRelationDerived indicates a derived table (subquery) reference.
	QueryAccessRelationDerived QueryAccessRelationKind = "derived"
)

type QueryAccessRelationReference added in v0.380.0 

type QueryAccessRelationReference struct {
	Schema             string `json:"schema,omitempty"`
	Name               string `json:"name"`
	Alias              string `json:"alias,omitempty"`
	Kind               string `json:"kind"`
	PermissionRequired bool   `json:"permission_required"`
	Unbound            bool   `json:"unbound,omitempty"`
}

QueryAccessRelationReference represents a relation read by the query.

type QueryAccessRelationSchema added in v0.380.0 

type QueryAccessRelationSchema struct {
	Schema  string
	Name    string
	Kind    string
	Columns []QueryAccessColumnSchema
	IsView  bool
}

QueryAccessRelationSchema contains metadata about a relation for resolution.

type QueryAccessRequest added in v0.380.0 

type QueryAccessRequest struct {
	SQL            string
	Dialect        Dialect
	Mode           QueryAccessMode
	DefaultSchema  string
	SchemaResolver QueryAccessSchemaResolver // optional
}

QueryAccessRequest is the input for query access analysis.

type QueryAccessRequirement added in v0.380.0 

type QueryAccessRequirement struct {
	Object    string `json:"object"`
	Privilege string `json:"privilege"`
}

QueryAccessRequirement represents a permission requirement.

type QueryAccessResult added in v0.380.0 

type QueryAccessResult struct {
	Dialect            string                         `json:"dialect"`
	Mode               QueryAccessMode                `json:"mode"`
	ReadClassification QueryAccessReadClassification  `json:"read_classification"`
	Admission          QueryAccessAdmission           `json:"admission"`
	ReasonCodes        []string                       `json:"reason_codes,omitempty"`
	Relations          []QueryAccessRelationReference `json:"relations,omitempty"`
	ReferencedColumns  []QueryAccessColumnReference   `json:"referenced_columns,omitempty"`
	Outputs            []QueryAccessOutputColumn      `json:"outputs,omitempty"`
	Requirements       []QueryAccessRequirement       `json:"requirements,omitempty"`
	Unresolved         []QueryAccessUnresolved        `json:"unresolved,omitempty"`
	Warnings           []string                       `json:"warnings,omitempty"`
}

QueryAccessResult is the output of query access analysis.

func AnalyzePostgreSQLQueryAccessWithSession added in v0.390.0 

func AnalyzePostgreSQLQueryAccessWithSession(_ context.Context, _ *PostgreSQLQueryAccessSession, _ QueryAccessRequest) (*QueryAccessResult, error)

AnalyzePostgreSQLQueryAccessWithSession returns ErrPostgreSQLSessionNotAvailable when built without the postgresql tag.

func AnalyzeQueryAccess added in v0.380.0 

func AnalyzeQueryAccess(ctx context.Context, req QueryAccessRequest) (*QueryAccessResult, error)

AnalyzeQueryAccess performs query access analysis.

type QueryAccessSchemaResolver added in v0.380.0 

type QueryAccessSchemaResolver interface {
	ResolveRelation(ctx context.Context, dialect, schema, name string) (QueryAccessRelationSchema, error)
}

QueryAccessSchemaResolver resolves relation metadata for name resolution.

type QueryAccessUnresolved added in v0.380.0 

type QueryAccessUnresolved struct {
	Reference string `json:"reference"`
	Reason    string `json:"reason"`
}

QueryAccessUnresolved represents an unresolved reference.

type Request 

type Request struct {
	SQL              string
	Dialect          Dialect
	ConfigPath       string
	Schema           string
	MetadataProvider MetadataProvider
}

Request describes one public audit invocation.

type Result 

type Result struct {
	Verdict        Verdict                  `json:"verdict"`
	Summary        Summary                  `json:"summary"`
	Statements     []StatementResult        `json:"statements,omitempty"`
	GlobalFindings []Finding                `json:"global_findings,omitempty"`
	Unsupported    []spec.UnsupportedDetail `json:"unsupported,omitempty"`
	Explanation    *Explanation             `json:"explanation,omitempty"`
	Diagnostics    []spec.Diagnostic        `json:"diagnostics,omitempty"`
}

Result is the stable public audit output.

func Audit 

func Audit(ctx context.Context, request Request) (Result, error)

Audit executes the stable public audit flow.

type StatementResult 

type StatementResult struct {
	Index         int          `json:"index"`
	Kind          string       `json:"kind"`
	RawSQL        string       `json:"raw_sql,omitempty"`
	NormalizedSQL string       `json:"normalized_sql,omitempty"`
	Findings      []Finding    `json:"findings,omitempty"`
	Impact        *Impact      `json:"impact,omitempty"`
	Explanation   *Explanation `json:"explanation,omitempty"`
}

StatementResult stores public findings for a single SQL statement.

type Summary 

type Summary struct {
	Statements int `json:"statements"`
	Blockers   int `json:"blockers"`
	Warnings   int `json:"warnings"`
	Notices    int `json:"notices"`
}

Summary captures high-level public audit counts.

type Table 

type Table = spec.Table

Table mirrors the domain table shape used inside metadata snapshots.

type TableSnapshot 

type TableSnapshot = spec.TableSnapshot

TableSnapshot mirrors metadata-aware target table snapshots for public providers.

type Verdict 

type Verdict string

Verdict identifies the final public audit outcome. 

const (
	VerdictPass   Verdict = "pass"
	VerdictReview Verdict = "review"
	VerdictReject Verdict = "reject"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.