riskenvelope

Documentation

Index

• Constants
• func CanonicalSHA256Ref(v any) (string, error)
• func EnvelopeID(salt []byte, sourcePackHash string) (string, error)
• func GenerateSalt() ([]byte, error)
• func LoadOrCreateSaltFile(path string) ([]byte, error)
• func Pseudonym(salt []byte, rawID string) (string, error)
• func SHA256Ref(data []byte) string
• type AgentSurface
• type BoundaryGrade
• type BoundaryGradeLetter
• type BoundaryGradeReason
• type CohortBucket
• type EnvelopeEvidence
• type EnvelopeFinding
• type IAMGrantBucket
• type IAMGrantBucketCount
• type OAuthScopeBucket
• type OAuthScopeBucketCount
• type PermissionMode
• type PostureProbe
• type PrivacyNonCollection
• type ResourceType
• type RiskCode
• type RiskEnvelope
  • func Seal(e RiskEnvelope) (RiskEnvelope, error)
  • func (e RiskEnvelope) ContentHash() (string, error)
  • func (e RiskEnvelope) Validate() error
• type Severity
• type ToolClass

Constants

const SaltBytes = 32

const SchemaVersion = "risk-envelope/v1"

Functions

func CanonicalSHA256Ref

func CanonicalSHA256Ref(v any) (string, error)

func EnvelopeID

func EnvelopeID(salt []byte, sourcePackHash string) (string, error)

func GenerateSalt

func GenerateSalt() ([]byte, error)

GenerateSalt returns a local-only CSPRNG salt for HMAC pseudonyms. Store this per customer/workstation and never upload it; low-entropy resource names are dictionary-reversible if the salt is weak or leaked.

func LoadOrCreateSaltFile

func LoadOrCreateSaltFile(path string) ([]byte, error)

LoadOrCreateSaltFile loads a hex-encoded local-only salt, or creates one with 0600 permissions. Existing salt files with group/world permissions are rejected because pseudonym privacy depends on salt secrecy.

func Pseudonym

func Pseudonym(salt []byte, rawID string) (string, error)

Pseudonym HMACs a raw local identifier into an upload-safe reference. The raw input can be low entropy; privacy depends on a CSPRNG, per-customer, local-only salt.

func SHA256Ref

func SHA256Ref(data []byte) string

Types

type AgentSurface

type AgentSurface string

const (
	AgentSurfaceUnknown       AgentSurface = "unknown"
	AgentSurfaceClaudeCode    AgentSurface = "claude_code"
	AgentSurfaceCodex         AgentSurface = "codex"
	AgentSurfaceGitHubActions AgentSurface = "github_actions"
	AgentSurfaceMCP           AgentSurface = "mcp"
)

type BoundaryGrade

type BoundaryGrade struct {
	Letter BoundaryGradeLetter `json:"letter"`
	Reason BoundaryGradeReason `json:"reason"`
}

BoundaryGrade is the A–F grade of the scanned agent execution surface. It grades declared and locally discoverable configuration; it does not observe what an agent executed at runtime. Optional: a receipt projection has no static tree to grade and omits it.

type BoundaryGradeLetter

type BoundaryGradeLetter string

const (
	BoundaryGradeA BoundaryGradeLetter = "A"
	BoundaryGradeB BoundaryGradeLetter = "B"
	BoundaryGradeC BoundaryGradeLetter = "C"
	BoundaryGradeD BoundaryGradeLetter = "D"
	BoundaryGradeF BoundaryGradeLetter = "F"
)

type BoundaryGradeReason

type BoundaryGradeReason string

BoundaryGradeReason is the one-line justification for a grade. It is not free text: only the grader's own deterministic sentences validate.

type CohortBucket

type CohortBucket string

const (
	CohortUnknown      CohortBucket = "unknown"
	CohortRepos1To10   CohortBucket = "1-10repos"
	CohortRepos11To50  CohortBucket = "11-50repos"
	CohortRepos51To200 CohortBucket = "51-200repos"
	CohortRepos201Plus CohortBucket = "201plusrepos"
)

type EnvelopeEvidence

type EnvelopeEvidence struct {
	AgentTool             ToolClass      `json:"agent_tool,omitempty"`
	PermissionMode        PermissionMode `json:"permission_mode,omitempty"`
	BranchProtection      *bool          `json:"branch_protection,omitempty"`
	ProdEnvReviewers      *int           `json:"prod_env_reviewers,omitempty"`
	MCPWriteScopes        *bool          `json:"mcp_write_scopes,omitempty"`
	ManagedSettings       *bool          `json:"managed_settings,omitempty"`
	AuditLogging          *bool          `json:"audit_logging,omitempty"`
	SchemaPinned          *bool          `json:"schema_pinned,omitempty"`
	DirectDispatchSeen    *bool          `json:"direct_dispatch_seen,omitempty"`
	SecretValueAccessible *bool          `json:"secret_value_accessible,omitempty"`
}

type EnvelopeFinding

type EnvelopeFinding struct {
	ResourceID   string           `json:"resource_id"`
	ResourceType ResourceType     `json:"resource_type"`
	RiskCode     RiskCode         `json:"risk_code"`
	Severity     Severity         `json:"severity"`
	Evidence     EnvelopeEvidence `json:"evidence"`
}

type IAMGrantBucket

type IAMGrantBucket string

const (
	IAMGrantNone    IAMGrantBucket = "none"
	IAMGrantRead    IAMGrantBucket = "read"
	IAMGrantWrite   IAMGrantBucket = "write"
	IAMGrantAdmin   IAMGrantBucket = "admin"
	IAMGrantCloud   IAMGrantBucket = "cloud"
	IAMGrantDeploy  IAMGrantBucket = "deploy"
	IAMGrantBilling IAMGrantBucket = "billing"
	IAMGrantUnknown IAMGrantBucket = "unknown"
)

type IAMGrantBucketCount

type IAMGrantBucketCount struct {
	Bucket IAMGrantBucket `json:"bucket"`
	Count  int            `json:"count"`
}

type OAuthScopeBucket

type OAuthScopeBucket string

const (
	OAuthScopeNone     OAuthScopeBucket = "none"
	OAuthScopeRead     OAuthScopeBucket = "read"
	OAuthScopeWrite    OAuthScopeBucket = "write"
	OAuthScopeAdmin    OAuthScopeBucket = "admin"
	OAuthScopeRepo     OAuthScopeBucket = "repo"
	OAuthScopeWorkflow OAuthScopeBucket = "workflow"
	OAuthScopeCloud    OAuthScopeBucket = "cloud"
	OAuthScopeDB       OAuthScopeBucket = "db"
	OAuthScopeUnknown  OAuthScopeBucket = "unknown"
)

type OAuthScopeBucketCount

type OAuthScopeBucketCount struct {
	Bucket OAuthScopeBucket `json:"bucket"`
	Count  int              `json:"count"`
}

type PermissionMode

type PermissionMode string

const (
	PermissionModeUnknown           PermissionMode = "unknown"
	PermissionModePlan              PermissionMode = "plan"
	PermissionModeAsk               PermissionMode = "ask"
	PermissionModeAcceptEdits       PermissionMode = "accept_edits"
	PermissionModeBypassPermissions PermissionMode = "bypass_permissions"
)

type PostureProbe

type PostureProbe struct {
	AgentSurface           AgentSurface            `json:"agent_surface"`
	PermissionMode         PermissionMode          `json:"permission_mode"`
	ManagedSettingsPresent bool                    `json:"managed_settings_present"`
	MCPServerCount         int                     `json:"mcp_server_count"`
	OAuthScopeBuckets      []OAuthScopeBucketCount `json:"oauth_scope_buckets"`
	IAMGrantBuckets        []IAMGrantBucketCount   `json:"iam_grant_buckets"`
	StaticConfigFilesRead  int                     `json:"static_config_files_read"`
	MetadataAPICalls       int                     `json:"metadata_api_calls"`
	SuppressedFindingCount int                     `json:"suppressed_finding_count"`
	KAnonymityFloor        int                     `json:"k_anonymity_floor"`
}

type PrivacyNonCollection

type PrivacyNonCollection struct {
	RawPromptsCollected   bool `json:"raw_prompts_collected"`
	SourceCodeCollected   bool `json:"source_code_collected"`
	SecretValuesCollected bool `json:"secret_values_collected"`
	CommandBodiesExported bool `json:"command_bodies_exported"`
}

type ResourceType

type ResourceType string

const (
	ResourceRepo              ResourceType = "repo"
	ResourceMCPServer         ResourceType = "mcp_server"
	ResourceWorkflow          ResourceType = "workflow"
	ResourceSecretClass       ResourceType = "secret_class"
	ResourcePermissionProfile ResourceType = "permission_profile"
	ResourceEnvironment       ResourceType = "environment"
	ResourceOAuthClient       ResourceType = "oauth_client"
	ResourceIAMPrincipal      ResourceType = "iam_principal"
)

type RiskCode

type RiskCode string

const (
	RiskAgentWriteWithoutEnvApproval RiskCode = "AGENT_WRITE_WITHOUT_ENV_APPROVAL"
	RiskBroadShellAllow              RiskCode = "BROAD_SHELL_ALLOW"
	RiskBypassPermissionsEnabled     RiskCode = "BYPASS_PERMISSIONS_ENABLED"
	RiskMCPWriteScopeWithoutApproval RiskCode = "MCP_WRITE_SCOPE_WITHOUT_APPROVAL"
	RiskProdEnvWithoutReviewers      RiskCode = "PROD_ENV_WITHOUT_REVIEWERS"
	RiskSecretClassAgentReadable     RiskCode = "SECRET_CLASS_AGENT_READABLE"
	RiskDirectDispatchSeen           RiskCode = "DIRECT_DISPATCH_SEEN"
	RiskNoManagedSettings            RiskCode = "NO_MANAGED_SETTINGS"
	RiskNoAuditExport                RiskCode = "NO_AUDIT_EXPORT"
	RiskNoBranchProtection           RiskCode = "NO_BRANCH_PROTECTION"
	RiskSchemaPinMissing             RiskCode = "SCHEMA_PIN_MISSING"
	RiskIAMAdminGrantVisible         RiskCode = "IAM_ADMIN_GRANT_VISIBLE"
	RiskOAuthHighRiskScope           RiskCode = "OAUTH_HIGH_RISK_SCOPE"
	RiskCIWorkflowWriteToken         RiskCode = "CI_WORKFLOW_WRITE_TOKEN"
)

type RiskEnvelope

type RiskEnvelope struct {
	SchemaVersion       string               `json:"schema_version"`
	EnvelopeID          string               `json:"envelope_id"`
	EnvelopeContentHash string               `json:"envelope_content_hash"`
	CohortBucket        CohortBucket         `json:"cohort_bucket"`
	SourcePackHash      string               `json:"source_pack_hash"`
	BoundaryGrade       *BoundaryGrade       `json:"boundary_grade,omitempty"`
	Findings            []EnvelopeFinding    `json:"findings"`
	Posture             PostureProbe         `json:"posture"`
	Privacy             PrivacyNonCollection `json:"privacy"`
	GeneratedAt         time.Time            `json:"generated_at"`
}

func Seal

func Seal(e RiskEnvelope) (RiskEnvelope, error)

func (RiskEnvelope) ContentHash

func (e RiskEnvelope) ContentHash() (string, error)

func (RiskEnvelope) Validate

func (e RiskEnvelope) Validate() error

type Severity

type Severity string

const (
	SeverityInfo     Severity = "INFO"
	SeverityLow      Severity = "LOW"
	SeverityMedium   Severity = "MEDIUM"
	SeverityHigh     Severity = "HIGH"
	SeverityCritical Severity = "CRITICAL"
)

type ToolClass

type ToolClass string

const (
	ToolClassUnknown          ToolClass = "unknown"
	ToolClassGitPush          ToolClass = "git_push"
	ToolClassGitWrite         ToolClass = "git_write"
	ToolClassDBWrite          ToolClass = "db_write"
	ToolClassMCPWrite         ToolClass = "mcp_write"
	ToolClassMCPRead          ToolClass = "mcp_read"
	ToolClassDeployPublish    ToolClass = "deploy_publish"
	ToolClassSecretRead       ToolClass = "secret_read"
	ToolClassPaymentInitiate  ToolClass = "payment_initiate"
	ToolClassShellOperate     ToolClass = "shell_operate"
	ToolClassNetworkEgress    ToolClass = "network_egress"
	ToolClassWorkflowDispatch ToolClass = "workflow_dispatch"
)