scoring

package
v0.4.17 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 5 Imported by: 0

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

View Source
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

ConfidenceFactor scales risk by how sure Scout is.

DefaultWeights weight categories in the overall score; app and API security count most.

View Source
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.

View Source
var Now = time.Now

Now is the clock used to expire accepted risks. Tests override it.

SeverityBase is the base risk of each severity.

Functions

func Counts

func Counts(f core.Finding) bool

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

func Criticality(a core.Asset) float64

Criticality returns the asset's criticality multiplier, defaulting to 1.

func ExposureFactor

func ExposureFactor(e core.Exposure) float64

ExposureFactor scales risk by who can reach the asset. An unknown exposure counts as internet-facing: when unsure, assume the worst.

func Grade

func Grade(score float64) string

Grade maps a score to a letter: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, else F.

func Risk

func Risk(f core.Finding) float64

Risk is a finding's weight: severity_base × confidence × exposure × asset_criticality.

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.

func FixNext

func FixNext(findings []core.Finding, opts Options) []FixItem

FixNext ranks open findings by points regained per effort hour, highest first. Ties break on severity, then fingerprint, so order is stable.

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.

func Score

func Score(findings []core.Finding, opts Options) Report

Score computes the report for findings.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL