Documentation
¶
Overview ¶
Package analyzer provides security risk scoring, policy enforcement, and audit reporting for forge skills.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatJSON ¶
func FormatJSON(report *AuditReport) ([]byte, error)
FormatJSON serializes an AuditReport to indented JSON.
func FormatText ¶
func FormatText(report *AuditReport) string
FormatText produces a human-readable text representation of an AuditReport.
Types ¶
type AuditReport ¶
type AuditReport struct {
Timestamp string `json:"timestamp"`
SkillCount int `json:"skill_count"`
AggregateScore RiskScore `json:"aggregate_score"`
Assessments []SkillRiskAssessment `json:"assessments"`
PolicySummary PolicySummary `json:"policy_summary"`
}
AuditReport is the complete security audit output.
func GenerateReport ¶
func GenerateReport(registry contract.SkillRegistry, policy SecurityPolicy) (*AuditReport, error)
GenerateReport produces a full audit report from a SkillRegistry.
Registry skills carry fully-typed SkillDescriptors (capabilities, trust hints, deny_output presence populated by the scanner), so this path analyzes descriptors directly rather than round-tripping through entries, which would drop those fields.
func GenerateReportFromEntries ¶
func GenerateReportFromEntries(entries []contract.SkillEntry, hasScript func(string) bool, policy SecurityPolicy) *AuditReport
GenerateReportFromEntries produces an audit report from parsed skill entries.
type PolicySummary ¶
type PolicySummary struct {
TotalViolations int `json:"total_violations"`
Errors int `json:"errors"`
Warnings int `json:"warnings"`
Passed bool `json:"passed"`
}
PolicySummary aggregates policy violation counts.
type PolicyViolation ¶
type PolicyViolation struct {
Rule string `json:"rule"`
Severity string `json:"severity"` // "error", "warning"
Message string `json:"message"`
}
PolicyViolation describes a security policy breach.
func CheckPolicy ¶
func CheckPolicy(sd *contract.SkillDescriptor, hasScript bool, policy SecurityPolicy) []PolicyViolation
CheckPolicy evaluates a SkillDescriptor against a SecurityPolicy.
func CheckPolicyFromEntry ¶
func CheckPolicyFromEntry(entry *contract.SkillEntry, hasScript bool, policy SecurityPolicy) []PolicyViolation
CheckPolicyFromEntry evaluates a SkillEntry against a SecurityPolicy. It builds a temporary SkillDescriptor from the entry's metadata.
type RiskFactor ¶
type RiskFactor struct {
Category string `json:"category"` // "egress", "binary", "env", "script"
Description string `json:"description"`
Points int `json:"points"`
}
RiskFactor is a single contributing factor to a risk score.
type SecurityPolicy ¶
type SecurityPolicy struct {
// Policy checks.
MaxEgressDomains int `yaml:"max_egress_domains" json:"max_egress_domains"`
BinaryDenylist []string `yaml:"binary_denylist" json:"binary_denylist,omitempty"`
DeniedEnvPatterns []string `yaml:"denied_env_patterns" json:"denied_env_patterns,omitempty"`
ScriptPolicy string `yaml:"script_policy" json:"script_policy"` // "allow"|"warn"|"deny"
MaxRiskScore int `yaml:"max_risk_score" json:"max_risk_score"`
MaxTags int `yaml:"max_tags" json:"max_tags"`
// Scoring overrides.
TrustedDomains []string `yaml:"trusted_domains" json:"trusted_domains,omitempty"` // egress domains scored as trusted (+2) instead of unknown (+10)
AcknowledgedBins []string `yaml:"acknowledged_bins" json:"acknowledged_bins,omitempty"` // builtin high-risk binaries scored as standard (+3) instead of high-risk (+15)
AcknowledgedEnv []string `yaml:"acknowledged_env" json:"acknowledged_env,omitempty"` // env vars matching builtin sensitive patterns scored as standard (+5) instead of sensitive (+10)
}
SecurityPolicy defines configurable security rules.
Policy-check fields raise PolicyViolations during CheckPolicy. Scoring override fields influence how AnalyzeSkill* assigns points — they reduce the score for items an operator has explicitly accepted, and the affected RiskFactor's Description is annotated with "(via policy)" so the override is visible in the audit report.
func DefaultPolicy ¶
func DefaultPolicy() SecurityPolicy
DefaultPolicy returns a SecurityPolicy with sensible defaults.
MaxRiskScore=90 is the ceiling for vetted multi-purpose skills. The bundled code-review skill (6 egress domains + 9 config-knob env vars + a backing script) lands in the 75–85 band under the standard scoring rules; the legacy 75 ceiling would block it out of the box. Operators who want a stricter posture can lower the ceiling via a SecurityPolicy YAML file passed through `forge build --policy` or `security.policy_path` in forge.yaml.
func LoadPolicyFromFile ¶
func LoadPolicyFromFile(path string) (SecurityPolicy, error)
LoadPolicyFromFile reads a YAML SecurityPolicy from path. Unspecified fields take their zero value, which means no override is applied — a minimal policy file can omit any rule it doesn't intend to change.
type SkillRiskAssessment ¶
type SkillRiskAssessment struct {
SkillName string `json:"skill_name"`
Score RiskScore `json:"score"`
Factors []RiskFactor `json:"factors"`
Violations []PolicyViolation `json:"violations,omitempty"`
Recommendations []string `json:"recommendations,omitempty"`
}
SkillRiskAssessment is the security assessment for a single skill.
func AnalyzeSkillDescriptor ¶
func AnalyzeSkillDescriptor(sd *contract.SkillDescriptor, hasScript bool, policy SecurityPolicy) SkillRiskAssessment
AnalyzeSkillDescriptor scores a SkillDescriptor for security risk under the given policy. A zero-value SecurityPolicy{} preserves the historical default scoring (no overrides applied).
func AnalyzeSkillEntry ¶
func AnalyzeSkillEntry(entry *contract.SkillEntry, hasScript bool, policy SecurityPolicy) SkillRiskAssessment
AnalyzeSkillEntry scores a SkillEntry for security risk under the given policy. A zero-value SecurityPolicy{} preserves the historical default scoring (no overrides applied).
Source Files