Documentation
¶
Overview ¶
Package scoring turns findings into a 0-100 score, a letter grade, per-category subscores and the "fix next" ranking.
Package scoring turns findings into a 0-100 score, a letter grade, per-category subscores and the "fix next" ranking. It is deterministic: the same findings and options always produce the same report.
Index ¶
Constants ¶
const DefaultK = 50.0
DefaultK is the decay constant: a category's score is 100·e^(−Σrisk/K). With K = 50 one confirmed internet-facing critical (risk 40) leaves a category at 45, one high at 67, one medium at 85 and one low at 96.
Variables ¶
var ConfidenceFactor = map[core.Confidence]float64{ core.ConfidenceConfirmed: 1.0, core.ConfidenceLikely: 0.7, core.ConfidencePossible: 0.4, }
ConfidenceFactor scales risk by how sure Scout is.
var DefaultWeights = map[core.Category]float64{ core.CategoryApp: 3, core.CategoryAPI: 3, core.CategoryAuth: 3, core.CategoryExposure: 2, core.CategoryCode: 2, core.CategoryTLS: 1.5, core.CategoryConfig: 1.5, core.CategoryNetwork: 1.5, core.CategoryHost: 1.5, core.CategoryHeaders: 1, core.CategoryDNS: 1, }
DefaultWeights weight categories in the overall score; app and API security count most.
var EffortHours = map[core.Effort]float64{core.EffortS: 1, core.EffortM: 3, core.EffortL: 8}
EffortHours is the relative cost of each effort size. A missing effort counts as medium.
var Now = time.Now
Now is the clock used to expire accepted risks. Tests override it.
var SeverityBase = map[core.Severity]float64{ core.SeverityCritical: 40, core.SeverityHigh: 20, core.SeverityMedium: 8, core.SeverityLow: 2, core.SeverityInfo: 0, }
SeverityBase is the base risk of each severity.
Functions ¶
func Counts ¶
Counts reports whether a finding contributes to the score: open findings and accepted risks whose expiry has passed. Fixed, false-positive and still-accepted findings are ignored.
func Criticality ¶
Criticality returns the asset's criticality multiplier, defaulting to 1.
func ExposureFactor ¶
ExposureFactor scales risk by who can reach the asset. An unknown exposure counts as internet-facing: when unsure, assume the worst.
Types ¶
type Cap ¶
type Cap struct {
Grade string `json:"grade"`
Reason string `json:"reason"`
Fingerprint string `json:"fingerprint"`
Title string `json:"title"`
}
Cap is a hard limit on the grade caused by one finding, SSL Labs style: one serious flaw caps the grade however good everything else is.
type CategoryScore ¶
type CategoryScore struct {
Category core.Category `json:"category"`
Score float64 `json:"score"`
Grade string `json:"grade"`
Risk float64 `json:"risk"`
Findings int `json:"findings"` // open findings counted
// Worst is the worst open severity, used to color the subscore bar.
Worst core.Severity `json:"worst"`
}
CategoryScore is one category's subscore.
type CriticalityRule ¶
type CriticalityRule struct {
// Host is an exact host or "*.example.com"; empty matches any host.
Host string `json:"host,omitempty" yaml:"host"`
// PathPrefix narrows the rule to paths under it; empty matches any path.
PathPrefix string `json:"path_prefix,omitempty" yaml:"path_prefix"`
Value float64 `json:"value" yaml:"value"`
}
CriticalityRule sets how much an asset matters. Examples: a payments API at 1.5, a marketing site at 0.7.
type FixItem ¶
type FixItem struct {
Fingerprint string `json:"fingerprint"`
CheckID string `json:"check_id"`
Title string `json:"title"`
Severity core.Severity `json:"severity"`
Asset string `json:"asset"`
Effort core.Effort `json:"effort"`
// Points is how much the overall score rises if this alone is fixed:
// the larger of the capped gain (lifting a cap) and the uncapped gain.
// Using the uncapped gain too keeps findings rankable while a cap from
// another finding holds the capped score flat.
Points float64 `json:"points"`
// Priority is Points per effort hour: the safety bought per hour.
Priority float64 `json:"priority"`
}
FixItem is one entry in the "fix next" list.
type Options ¶
type Options struct {
K float64
Weights map[core.Category]float64
// Assessed lists the categories the scan actually covered. Only these
// enter the overall score, so a scan that never looked at host security
// does not get a free 100 for it. Nil means every category with findings
// plus every weighted category.
Assessed []core.Category
// Criticality rules apply to assets without their own Criticality.
Criticality []CriticalityRule
}
Options tune scoring. The zero value uses the defaults.
type Report ¶
type Report struct {
Score float64 `json:"score"`
Grade string `json:"grade"`
Categories []CategoryScore `json:"categories"`
// Uncapped is the weighted score before hard caps.
Uncapped float64 `json:"uncapped"`
Caps []Cap `json:"caps,omitempty"`
}
Report is the scored outcome of a set of findings. When nothing was assessed, Grade is empty and Score is 0.