securitymanifest

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jun 22, 2026 License: MPL-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package securitymanifest projects the stable compiler IR into a declarative, machine-readable security posture (gowdk-security.json). It records what the generated app actually exposes — every route, backend endpoint, and contract with its guards, CSRF state, body limit, and source location, plus the frontend surface (raw-HTML sinks, secret scan, header configuration, and client route-guard coverage).

The manifest is "what is": it never decides whether the posture is acceptable. Policy evaluation and findings live in internal/auditspec, which consumes this manifest. Keeping the projection free of policy keeps gowdk-security.json stable and equally auditable by a human or an LLM regardless of which policies are declared.

Index

Constants

View Source 
const PublicGuardID = "public"

PublicGuardID is the guard ID that marks an intentionally public target.

View Source 
const SchemaVersion = 1

SchemaVersion is the gowdk-security.json schema version.

Variables

This section is empty.

Functions

func RawHTMLFingerprint added in v0.8.0 

func RawHTMLFingerprint(ownerKind, ownerID, field, source string, ordinal int) string

RawHTMLFingerprint derives the stable identity of one raw-HTML sink. It is exported so tooling and tests can compute the value a policy exception must pin. The source location is part of the identity, so moving the sink (or changing its expression) produces a new fingerprint and stops a stale exception from suppressing a different sink.

Types

type BundleLeak 

type BundleLeak struct {
	Source string `json:"source"`
	Kind   string `json:"kind"`
}

BundleLeak records a secret-shaped value found in embedded output or build-time data.

type CORSPosture added in v0.8.0 

type CORSPosture struct {
	Enabled          bool     `json:"enabled"`
	AllowsAnyOrigin  bool     `json:"allowsAnyOrigin"`
	AllowedOrigins   []string `json:"allowedOrigins,omitempty"`
	AllowCredentials bool     `json:"allowCredentials"`
	MaxAgeSeconds    int      `json:"maxAgeSeconds,omitempty"`
	Origin           string   `json:"origin,omitempty"`
}

CORSPosture records the generated cross-origin policy for API and web contract endpoints. The zero value means CORS is disabled and endpoints stay same-origin.

type ConfiguredHeader 

type ConfiguredHeader struct {
	Name  string `json:"name"`
	Value string `json:"value,omitempty"`
}

ConfiguredHeader records one header configured for generated runtime output. Value carries the normalized effective value so audit policy can distinguish a weak configuration (for example Content-Security-Policy: *) from a meaningful one. Secret-shaped values are redacted so the posture stays safe to publish.

type ContractEntry 

type ContractEntry struct {
	Name              string   `json:"name"`
	Kind              string   `json:"kind"`
	Roles             []string `json:"roles,omitempty"`
	Status            string   `json:"status,omitempty"`
	DeclarationSource string   `json:"declarationSource,omitempty"`
	ExposureSource    string   `json:"exposureSource,omitempty"`
	SourceAttribution string   `json:"sourceAttribution"`
}

ContractEntry is the posture of one command/query contract reference.

type EndpointEntry 

type EndpointEntry struct {
	ID             string              `json:"id"`
	Kind           string              `json:"kind"`
	Method         string              `json:"method,omitempty"`
	Path           string              `json:"path,omitempty"`
	Guards         []string            `json:"guards,omitempty"`
	GuardEvidence  []GuardEvidence     `json:"guardEvidence,omitempty"`
	CSRF           bool                `json:"csrf"`
	BodyLimitBytes int64               `json:"bodyLimitBytes,omitempty"`
	RequestLimits  RequestLimitPosture `json:"requestLimits"`
	Public         bool                `json:"public"`
	DefaultDeny    bool                `json:"defaultDeny"`
	PageID         string              `json:"pageId,omitempty"`
	Source         string              `json:"source,omitempty"`
}

EndpointEntry is the posture of one backend action/api/fragment/contract endpoint.

type EvidenceState added in v0.8.0 

type EvidenceState string

EvidenceState classifies the kind of proof behind a security posture claim or audit finding. It is the shared vocabulary used by gowdk-security.json and the gowdk audit report so a human or CI can tell a statically proven fact from an app-owned obligation gowdk cannot verify. 

const (
	// EvidenceVerifiedStatic marks a fact the compiler proves from generated
	// output or the IR: CSRF wiring, body-limit installation, native guard
	// resolution, configured response headers, raw-HTML sink inventory.
	EvidenceVerifiedStatic EvidenceState = "verified-static"
	// EvidenceVerifiedRuntime marks a fact a generated runtime test exercised
	// against a real generated app (gowdk audit --run).
	EvidenceVerifiedRuntime EvidenceState = "verified-runtime"
	// EvidenceDeclared marks a control the project declared but gowdk has not
	// independently verified.
	EvidenceDeclared EvidenceState = "declared"
	// EvidenceUnverifiedAppOwned marks a control whose decision logic is owned by
	// the application: gowdk generates the call site but cannot prove correctness.
	EvidenceUnverifiedAppOwned EvidenceState = "unverified-app-owned"
	// EvidenceNotApplicable marks a posture item that needs no control: an
	// intentionally public target, or a control the surface does not require.
	EvidenceNotApplicable EvidenceState = "not-applicable"
	// EvidenceWaived marks a finding suppressed by an explicit, justified waiver.
	EvidenceWaived EvidenceState = "waived"
)

func (EvidenceState) Valid added in v0.8.0 

func (state EvidenceState) Valid() bool

Valid reports whether state is a known evidence classification.

type FrontendSurface 

type FrontendSurface struct {
	UnguardedRoutes   []UnguardedRoute   `json:"unguardedRoutes"`
	BundleSecrets     []BundleLeak       `json:"bundleSecrets"`
	RawHTMLSinks      []RawHTMLSink      `json:"rawHtmlSinks"`
	ConfiguredHeaders []ConfiguredHeader `json:"configuredHeaders"`
}

FrontendSurface describes the build-time / client-facing security surface. Policy evaluation consumes these posture facts without deciding whether they are acceptable here.

type GuardEvidence added in v0.8.0 

type GuardEvidence struct {
	ID                 string        `json:"id"`
	Kind               string        `json:"kind"`
	BindingStatus      string        `json:"bindingStatus"`
	Owner              string        `json:"owner"`
	Evidence           EvidenceState `json:"evidence"`
	ExecutionPhase     string        `json:"executionPhase"`
	FailureContract    string        `json:"failureContract"`
	RuntimeTestFixture string        `json:"runtimeTestFixture,omitempty"`
}

GuardEvidence records what the compiler can prove about one declared guard. App-owned guards are intentionally classified as unverified unless an application-supplied fixture exercises them outside the synthetic audit hook.

type ObligationEntry added in v0.8.0 

type ObligationEntry struct {
	ID       string        `json:"id"`
	Category string        `json:"category"`
	Claim    string        `json:"claim"`
	Owner    string        `json:"owner"`
	Evidence EvidenceState `json:"evidence"`
	Detail   string        `json:"detail,omitempty"`
}

ObligationEntry records one security obligation and how strongly gowdk can vouch for it. Statically generated controls (CSRF wiring, body limits, security headers, native guards) are verified-static; app-owned controls (authentication, session management, tenant/resource authorization, domain authorization) are unverified-app-owned because gowdk generates the call sites but does not own the decision logic. This list keeps gowdk-security.json honest about what the compiler proves versus what the application must prove itself.

type ObservabilityEntry added in v0.8.0 

type ObservabilityEntry struct {
	ID                         string   `json:"id"`
	Kind                       string   `json:"kind"`
	Path                       string   `json:"path,omitempty"`
	Methods                    []string `json:"methods,omitempty"`
	Mounted                    bool     `json:"mounted"`
	AccessPolicy               string   `json:"accessPolicy"`
	BuildMode                  string   `json:"buildMode"`
	DevOnly                    bool     `json:"devOnly"`
	AllowedOrigins             []string `json:"allowedOrigins,omitempty"`
	ContentTypeRequired        string   `json:"contentTypeRequired,omitempty"`
	BodyLimitBytes             int64    `json:"bodyLimitBytes,omitempty"`
	BatchLimit                 int      `json:"batchLimit,omitempty"`
	SubscriberLimit            int      `json:"subscriberLimit,omitempty"`
	SourceMetadataPolicy       string   `json:"sourceMetadataPolicy,omitempty"`
	ExportsAbsoluteSourcePaths bool     `json:"exportsAbsoluteSourcePaths,omitempty"`
	SpanDataLeavesProcess      bool     `json:"spanDataLeavesProcess"`
}

ObservabilityEntry records one generated trace endpoint or export surface.

type RawHTMLSink 

type RawHTMLSink struct {
	OwnerKind   string `json:"ownerKind"`
	OwnerID     string `json:"ownerId"`
	Field       string `json:"field"`
	Source      string `json:"source"`
	Ordinal     int    `json:"ordinal"`
	Fingerprint string `json:"fingerprint"`
}

RawHTMLSink records one raw-HTML (g:unsafe-html) render site. Fingerprint is a stable identity derived from the owner, source location, rendered field/expression, and the sink's ordinal within its owner, so a policy exception can target one exact sink and stop suppressing it when the source moves or the expression changes.

type RequestLimitPosture added in v0.8.0 

type RequestLimitPosture struct {
	EndpointKind           string `json:"endpointKind,omitempty"`
	RawBodyBytes           int64  `json:"rawBodyBytes"`
	DecodedObjectBytes     int64  `json:"decodedObjectBytes,omitempty"`
	MultipartEnabled       bool   `json:"multipartEnabled"`
	MultipartMaxBytes      int64  `json:"multipartMaxBytes,omitempty"`
	CompressedBodyHandling string `json:"compressedBodyHandling,omitempty"`
	InstalledBeforeParse   bool   `json:"installedBeforeParse"`
	Phase                  string `json:"phase,omitempty"`
	Origin                 string `json:"origin,omitempty"`
}

RequestLimitPosture is the effective request-limit posture of one generated endpoint. It expresses more than a single byte cap: it distinguishes the raw body cap from decoded-object and multipart caps, records how compressed bodies are bounded, and records whether the cap is installed before the body is parsed (so a body limit precedes generated guards, CSRF token parsing, and handler execution). BodyLimitBytes on the parent entry mirrors RawBodyBytes.

type RouteEntry 

type RouteEntry struct {
	PageID        string          `json:"pageId"`
	Route         string          `json:"route"`
	Kind          string          `json:"kind"`
	Method        string          `json:"method,omitempty"`
	Render        string          `json:"render,omitempty"`
	Guards        []string        `json:"guards,omitempty"`
	GuardEvidence []GuardEvidence `json:"guardEvidence,omitempty"`
	Public        bool            `json:"public"`
	DefaultDeny   bool            `json:"defaultDeny"`
	Source        string          `json:"source,omitempty"`
}

RouteEntry is the posture of one page/file route.

type SecurityManifest 

type SecurityManifest struct {
	Version       int                  `json:"version"`
	GeneratedFrom string               `json:"generatedFrom"`
	BuildMode     string               `json:"buildMode,omitempty"`
	Routes        []RouteEntry         `json:"routes,omitempty"`
	Endpoints     []EndpointEntry      `json:"endpoints,omitempty"`
	Contracts     []ContractEntry      `json:"contracts,omitempty"`
	Observability []ObservabilityEntry `json:"observability,omitempty"`
	CORS          CORSPosture          `json:"cors"`
	Frontend      FrontendSurface      `json:"frontend"`
	Obligations   []ObligationEntry    `json:"obligations,omitempty"`
	Waivers       []WaiverDeclaration  `json:"waivers,omitempty"`
}

SecurityManifest is the declarative posture of one built module.

func Build 

func Build(config gowdk.Config, ir gwdkir.Program) SecurityManifest

Build projects validated IR into a SecurityManifest. It reuses compiler.BuildRouteMetadataFromIR so the posture matches the CLI routes and endpoints reports exactly.

type UnguardedRoute 

type UnguardedRoute struct {
	Route  string `json:"route"`
	Source string `json:"source,omitempty"`
}

UnguardedRoute records one client-visible route that relies on generated default-deny handling because the source declared no guard.

type WaiverDeclaration added in v0.8.0 

type WaiverDeclaration struct {
	Code          string `json:"code"`
	Target        string `json:"target,omitempty"`
	Owner         string `json:"owner,omitempty"`
	Justification string `json:"justification,omitempty"`
	Expires       string `json:"expires,omitempty"`
	Ticket        string `json:"ticket,omitempty"`
	PolicyDigest  string `json:"policyDigest,omitempty"`
	PostureDigest string `json:"postureDigest,omitempty"`
	Policy        string `json:"policy,omitempty"`
	Source        string `json:"source,omitempty"`
}

WaiverDeclaration records one declared `waive` rule from a *.audit.gwdk file, independent of whether it currently suppresses a finding. Recording the declared waivers in gowdk-security.json keeps every suppression decision visible in the build's security metadata; gowdk audit decides which ones are valid, expired, or stale.

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.