Documentation
¶
Overview ¶
Package spec is L0 of the SigComply CLI: parsers and validators for the declarative artifacts that drive the engine — framework specs, policy specs, evidence type schemas, source plugin manifests, the project config (.sigcomply.yaml), and the manual evidence catalog.
L0 owns the on-disk format. Nothing here executes; specs are read, validated, and handed up to L1 (types) and L2 (registries).
See docs/architecture/02-layers.md for the full layer contract.
Index ¶
- Constants
- func LoadEvidenceType(data []byte) (core.EvidenceType, error)
- func LoadPolicy(data []byte) (core.Policy, error)
- type BindingEntry
- type CIConfig
- type CloudConfig
- type ControlSpec
- type CustomPeriod
- type ExceptionConfig
- type ExceptionScope
- type ExtensionsConfig
- type FiscalCalendarConfig
- type FrameworkSpec
- type OutputConfig
- type PeriodConfig
- type PluginConfigField
- type PluginCredentialRequirement
- type PluginManifest
- type PolicyOverride
- type PolicyRefSpec
- type ProjectConfig
- type VaultConfig
Constants ¶
const ManualSlotName = "_manual"
ManualSlotName is the synthetic slot name the planner creates for manual policies. The collector and evaluator use it as the key in RecordsByPolicy[policyID].
Variables ¶
This section is empty.
Functions ¶
func LoadEvidenceType ¶
func LoadEvidenceType(data []byte) (core.EvidenceType, error)
LoadEvidenceType parses a JSON Schema document declaring an evidence type and returns the L1 core.EvidenceType. See docs/architecture/04-source-plugins.md §Evidence types for the canonical file shape.
The Schema field on the returned value is the original bytes verbatim — record-against-schema validation happens at L4 (M6) using a JSON Schema library; this loader only checks the wrapper fields it needs.
func LoadPolicy ¶
LoadPolicy parses a policy.yaml document and returns the L1 core.Policy with all fields populated.
Out of scope at L0: verifying that `control` exists in the framework's control catalog, that `rule` resolves in the rule registry, and that each `slot.type` exists in the evidence-type registry. Those are cross-spec checks handled by the planner (L3).
Types ¶
type BindingEntry ¶
type BindingEntry struct {
Source string `yaml:"source"`
SlotParams map[string]any `yaml:"slot_params"`
}
BindingEntry is one element of a slot binding list. It accepts both the string shape ("aws.iam") and the object shape with optional slot_params ({source: aws.iam, slot_params: {...}}).
func (*BindingEntry) UnmarshalYAML ¶
func (b *BindingEntry) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML accepts either a scalar string or a mapping; both are valid shapes in .sigcomply.yaml.
type CIConfig ¶
type CIConfig struct {
FailOnViolation *bool `yaml:"fail_on_violation"`
FailSeverity core.Severity `yaml:"fail_severity"`
}
CIConfig models CI exit-code behavior knobs.
type CloudConfig ¶
CloudConfig models the cloud submission section.
type ControlSpec ¶
type ControlSpec struct {
ID string `yaml:"id"`
Name string `yaml:"name"`
Description string `yaml:"description"`
Category string `yaml:"category"`
BaselineSeverity core.Severity `yaml:"baseline_severity"`
}
ControlSpec mirrors core.Control for YAML decoding.
type CustomPeriod ¶
type CustomPeriod struct {
ID string `yaml:"id"`
Start string `yaml:"start"`
End string `yaml:"end"`
}
CustomPeriod is one entry in a custom fiscal_calendar.periods list.
type ExceptionConfig ¶
type ExceptionConfig struct {
Policy string `yaml:"policy"`
Scope ExceptionScope `yaml:"scope"`
State string `yaml:"state"`
Reason string `yaml:"reason"`
ApprovedBy string `yaml:"approved_by"`
ApprovedAt string `yaml:"approved_at"`
ExpiresAt string `yaml:"expires_at"`
}
ExceptionConfig is one declarative waiver or N/A entry.
type ExceptionScope ¶
type ExceptionScope struct {
ResourceID string `yaml:"resource_id"`
ResourcePattern string `yaml:"resource_pattern"`
}
ExceptionScope narrows an exception to specific resources.
type ExtensionsConfig ¶
type ExtensionsConfig struct {
Path string `yaml:"path"`
}
ExtensionsConfig overrides extension discovery paths.
type FiscalCalendarConfig ¶
type FiscalCalendarConfig struct {
Type string `yaml:"type"`
Starts string `yaml:"starts"`
Periods []CustomPeriod `yaml:"periods"`
}
FiscalCalendarConfig models the period.fiscal_calendar subsection.
type FrameworkSpec ¶
type FrameworkSpec struct {
SchemaVersion string `yaml:"schema_version"`
IDValue string `yaml:"id"`
VersionValue string `yaml:"version"`
DisplayName string `yaml:"display_name"`
Description string `yaml:"description"`
ControlsList []ControlSpec `yaml:"controls"`
PoliciesList []PolicyRefSpec `yaml:"policies"`
}
FrameworkSpec is the loaded representation of a framework.yaml file. It satisfies core.Framework so callers may register the value directly with the framework registry.
A framework.yaml carries the framework's identity, the catalog of controls it certifies against, and the list of policy IDs that contribute evaluations. Policy specs themselves live in separate files (one directory per policy, per docs/architecture/03-policy- spec.md) — the framework spec only references them by ID.
func LoadFramework ¶
func LoadFramework(data []byte) (*FrameworkSpec, error)
LoadFramework parses a framework.yaml document. The returned value satisfies core.Framework and may be registered directly.
func (*FrameworkSpec) Controls ¶
func (f *FrameworkSpec) Controls() []core.Control
Controls implements core.Framework.
func (*FrameworkSpec) Policies ¶
func (f *FrameworkSpec) Policies() []core.PolicyRef
Policies implements core.Framework.
func (*FrameworkSpec) Version ¶
func (f *FrameworkSpec) Version() string
Version implements core.Framework.
type OutputConfig ¶
type OutputConfig struct {
Format string `yaml:"format"`
JSONPath string `yaml:"json_path"`
Verbose bool `yaml:"verbose"`
}
OutputConfig models output preferences.
type PeriodConfig ¶
type PeriodConfig struct {
FiscalCalendar FiscalCalendarConfig `yaml:"fiscal_calendar"`
TimeBasis string `yaml:"time_basis"`
}
PeriodConfig models the period section.
type PluginConfigField ¶
type PluginConfigField struct {
Type string `yaml:"type"`
Required bool `yaml:"required"`
Default any `yaml:"default"`
Enum []any `yaml:"enum"`
Description string `yaml:"description"`
}
PluginConfigField describes one knob in the plugin's config_schema. Default is left as `any` because the static type is named by the Type field (`string`, `int`, `bool`, etc.).
type PluginCredentialRequirement ¶
type PluginCredentialRequirement struct {
Source string `yaml:"source"`
EnvVar string `yaml:"env_var,omitempty"`
}
PluginCredentialRequirement declares one credential the plugin needs. `Source` names the mechanism (e.g. env_or_default_chain, env, file).
type PluginManifest ¶
type PluginManifest struct {
SchemaVersion string `yaml:"schema_version"`
ID string `yaml:"id"`
DisplayName string `yaml:"display_name"`
Version string `yaml:"version"`
Description string `yaml:"description"`
Emits []string `yaml:"emits"`
Singleton bool `yaml:"singleton"`
ConfigSchema map[string]PluginConfigField `yaml:"config_schema"`
RequiresCredentials []PluginCredentialRequirement `yaml:"requires_credentials"`
}
PluginManifest is the in-memory shape of a plugin's plugin.yaml. It declares the plugin's identity, the evidence types it emits, and the config_schema customers fill in under sources.<id> in .sigcomply.yaml. See docs/architecture/04-source-plugins.md.
There is no L1 core type for plugin manifests — they are metadata the planner (L3) reads to validate project config and build SlotRequest values; nothing flows from a manifest into the evidence or aggregation paths.
func LoadPluginManifest ¶
func LoadPluginManifest(data []byte) (PluginManifest, error)
LoadPluginManifest parses a plugin manifest YAML document. Unknown fields are rejected (typo-safety); refer to the comment-doc on the PluginManifest struct for the field set.
type PolicyOverride ¶ added in v0.24.0
type PolicyOverride struct {
EvidenceMode string `yaml:"evidence_mode"`
CatalogEntry string `yaml:"catalog_entry"`
}
PolicyOverride lets a project override the evidence_mode declared in a framework-shipped policy spec. The primary use case is flipping an automated policy to manual while API integrations are being built out, then reverting the override once the integration is ready.
evidence_mode: "manual" — requires catalog_entry evidence_mode: "automated" — catalog_entry must be absent
type PolicyRefSpec ¶
type PolicyRefSpec struct {
ID string `yaml:"id"`
}
PolicyRefSpec is one entry in the framework's policies list — a reference to a policy by ID. The actual policy.yaml lives elsewhere.
type ProjectConfig ¶
type ProjectConfig struct {
SchemaVersion string `yaml:"schema_version"`
Framework string `yaml:"framework"`
Period PeriodConfig `yaml:"period"`
Vault VaultConfig `yaml:"vault"`
Sources map[string]map[string]any `yaml:"sources"`
Bindings map[string]map[string][]BindingEntry `yaml:"bindings"`
PolicyParameters map[string]map[string]any `yaml:"policy_parameters"`
PolicyCadences map[string]string `yaml:"policy_cadences"`
PolicyOverrides map[string]PolicyOverride `yaml:"policy_overrides"`
Exceptions []ExceptionConfig `yaml:"exceptions"`
Cloud CloudConfig `yaml:"cloud"`
CIEnvironment map[string]any `yaml:"ci_environment"`
Output OutputConfig `yaml:"output"`
CI CIConfig `yaml:"ci"`
Extensions ExtensionsConfig `yaml:"extensions"`
}
ProjectConfig is the parsed shape of .sigcomply.yaml. See docs/architecture/08-project-config.md for the canonical field reference. Cross-spec resolution (does this binding's source exist? is this parameter declared on the named policy?) is the planner's job (L3 / M4) — this loader only validates what's expressible without the registries.
func LoadProjectConfig ¶
func LoadProjectConfig(data []byte) (ProjectConfig, error)
LoadProjectConfig parses a .sigcomply.yaml document. The file is the customer's source of truth, so all error messages name the field path to make corrections obvious.
type VaultConfig ¶
type VaultConfig struct {
Backend string `yaml:"backend"`
Bucket string `yaml:"bucket"`
Region string `yaml:"region"`
Prefix string `yaml:"prefix"`
Endpoint string `yaml:"endpoint"`
ForcePathStyle bool `yaml:"force_path_style"`
Profile string `yaml:"profile"`
RoleARN string `yaml:"role_arn"`
Path string `yaml:"path"`
Account string `yaml:"account"`
Container string `yaml:"container"`
}
VaultConfig models the vault section. Backend-specific fields are all declared optional at the YAML level; per-backend required-field checks happen in validate.
Source Files