capability

package
v1.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: Apache-2.0 Imports: 9 Imported by: 4

Documentation

Overview

Package capability is the OpenCTEM capability taxonomy: the closed, versioned list of acts a scan tool can perform ("scan.ports@1", "probe.http@1", ...), and the contract every implementation of an act honors.

A capability, not a tool, carries the facts about the act:

  • its phase (passive or active discovery, assessment, validation, collection) and so its CTEM stage;
  • its tier floor: how intrusive the act is at minimum. The platform assigns a tool's effective tier as the maximum of the floor, the tool's own request and the platform's classification; a tool can raise its tier, never lower it;
  • its typed input and output ports and the CTIS asset types each port carries;
  • its standard params, which every implementation maps to its own config;
  • the CTIS paths every report of the act must carry;
  • the MITRE ATT&CK techniques an adversary uses for the same act, the D3FEND defensive functions it performs and CAPEC attack patterns.

A tool declares which capabilities it implements; it cannot invent a capability or redefine one. The taxonomy is data (taxonomy.json, embedded) so the platform, the SDK and the sensor read one copy.

Versioning: a capability id carries a major version ("scan.ports@1"). A minor change (an optional param or output path) keeps the major; changing a port, removing or retyping a param or adding a required path is a new major, and both majors may be served at once.

Design: OpenCTEM RFC "Tool Contract v1".

Index

Constants

View Source 
const Version = 1

Version is the taxonomy format version.

Variables

This section is empty.

Functions

func JSON 

func JSON() []byte

JSON returns the embedded taxonomy document, for tools that render or export it.

func Markdown 

func Markdown() string

Markdown renders the taxonomy as the reference page docs/capabilities.md. A test keeps the committed page equal to this output.

func ParseRef 

func ParseRef(ref string) (id string, major int, ok bool)

ParseRef splits "scan.ports@1" into its id and major. A ref without a major ("scan.ports") returns major 0. ok is false for anything that is not a well-formed id; it does not say whether the capability exists.

Types

type Capability 

type Capability struct {
	ID          string `json:"id"`
	Major       int    `json:"major"`
	Status      Status `json:"status"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Phase       Phase  `json:"phase"`
	// TierFloor is the minimum intrusiveness tier of the act: 0 passive,
	// 1 active non-intrusive, 2 intrusive.
	TierFloor int        `json:"tier_floor"`
	InPorts   []PortType `json:"in_ports"`
	OutPorts  []PortType `json:"out_ports"`
	// ExtraOutputs are output kinds that ride along without being a port
	// ("asset:certificate", "dependency", "endpoint"); "asset:*" allows any
	// asset type.
	ExtraOutputs []string `json:"extra_outputs,omitempty"`
	// FindingTypes, when set, are the only CTIS finding types a report may
	// carry; empty means any.
	FindingTypes []string `json:"finding_types,omitempty"`
	Params       []Param  `json:"params"`
	// Outputs are the required-output rules (see Rule).
	Outputs []Rule   `json:"outputs"`
	ATTACK  []string `json:"attack,omitempty"`
	D3FEND  []string `json:"d3fend,omitempty"`
	CAPEC   []string `json:"capec,omitempty"`
	// CrossCutting capabilities are used by other flows (retests, imports),
	// never as a workflow node.
	CrossCutting bool         `json:"cross_cutting,omitempty"`
	Deprecated   *Deprecation `json:"deprecated,omitempty"`
}

Capability is one entry of the taxonomy at one major version.

func All 

func All() []Capability

All returns every capability, in display order.

func Lookup 

func Lookup(ref string) (Capability, bool)

Lookup returns the capability a ref names. "scan.ports@1" names that major; "scan.ports" names its highest major. A ref is matched exactly: no case folding and no whitespace trimming.

func Routed 

func Routed() []Capability

Routed returns the routed capabilities, in display order.

func (Capability) Accepts 

func (c Capability) Accepts(assetType string) bool

Accepts reports whether a target of the CTIS asset type may be handed to the capability: one of its input ports carries it.

func (Capability) CTEMStage 

func (c Capability) CTEMStage() string

CTEMStage is the CTEM stage of the capability's phase.

func (Capability) Check 

func (c Capability) Check(r *ctis.Report, opts CheckOptions) ([]Violation, error)

Check reports how a report misses the capability's contract: records the capability may not emit, and records that miss a required path. A nil result means the report conforms. The report is not modified.

Check is a producer and receiver aid: the runtime uses it before upload and the platform again at ingest. It does not replace ctis.Validate.

func (Capability) MayEmit 

func (c Capability) MayEmit(kind string) bool

MayEmit reports whether a report of the capability may carry an output of this kind: "asset:<ctis asset type>", "finding:<ctis finding type>", "dependency" or "endpoint". A capability may emit what its output ports carry, what its input ports carry (a tool re-observes its targets), its extra outputs, and findings of an allowed type when it has a finding output.

func (Capability) Param 

func (c Capability) Param(name string) (Param, bool)

Param returns the standard param with this name.

func (Capability) Ref 

func (c Capability) Ref() string

Ref is the versioned id, "scan.ports@1".

func (Capability) Runnable 

func (c Capability) Runnable() bool

Runnable reports whether the capability is routed.

func (Capability) Shapes 

func (c Capability) Shapes() []string

Shapes are the named output shapes, in declaration order.

type CheckOptions 

type CheckOptions struct {
	// Shape, when set, checks the rules of that shape and the unnamed rules
	// only; other named shapes are skipped.
	Shape string
	// MaxViolations stops the check after this many (default 100), so a
	// hostile report cannot make the result unbounded.
	MaxViolations int
}

CheckOptions narrow a check.

type Deprecation 

type Deprecation struct {
	Since      string `json:"since"`
	ReplacedBy string `json:"replaced_by,omitempty"`
	Message    string `json:"message,omitempty"`
}

Deprecation marks a capability major that is being replaced.

type Param 

type Param struct {
	Name        string    `json:"name"`
	Type        ParamType `json:"type"`
	Description string    `json:"description"`
	// Enum, when set, is the closed set of allowed values (for a list, of
	// each item).
	Enum []string `json:"enum,omitempty"`
	Min  *int     `json:"min,omitempty"`
	Max  *int     `json:"max,omitempty"`
}

Param is one standard param of a capability.

type ParamType 

type ParamType string

ParamType is the value type of a standard param. 

const (
	ParamString     ParamType = "string"
	ParamStringList ParamType = "string_list"
	ParamInteger    ParamType = "integer"
	ParamBoolean    ParamType = "boolean"
	// ParamPortList is a list of ports and port ranges ("80,443,8000-8100").
	ParamPortList ParamType = "port_list"
)

The closed set of param types.

type Phase 

type Phase string

Phase is the engagement phase of a capability. 

const (
	PhaseDiscoverPassive Phase = "discover.passive"
	PhaseDiscoverActive  Phase = "discover.active"
	PhaseAssess          Phase = "assess"
	PhaseValidate        Phase = "validate"
	PhaseCollect         Phase = "collect"
)

The closed set of phases.

type PhaseInfo 

type PhaseInfo struct {
	ID          Phase  `json:"id"`
	Label       string `json:"label"`
	CTEMStage   string `json:"ctem_stage"`
	Description string `json:"description"`
}

PhaseInfo describes one phase.

func LookupPhase 

func LookupPhase(p Phase) (PhaseInfo, bool)

LookupPhase returns a phase's description.

func Phases 

func Phases() []PhaseInfo

Phases returns the closed phase set, in order.

type PortType 

type PortType string

PortType is the type of a capability port. The set is closed; two ports connect only when their types are equal. 

const (
	PortRootDomain     PortType = "root_domain"
	PortHostname       PortType = "hostname"
	PortIP             PortType = "ip"
	PortCIDR           PortType = "cidr"
	PortService        PortType = "service"
	PortURL            PortType = "url"
	PortRepository     PortType = "repository"
	PortContainerImage PortType = "container_image"
	PortCloudAccount   PortType = "cloud_account"
	// PortFinding is an output sink, and an input only for capabilities that
	// act on findings (verify.finding).
	PortFinding PortType = "finding"
	// PortEndpoint is a stream of web endpoints (a method and a path on an
	// origin, CTIS 1.6 report.endpoints): sub-inventory of a url, not an
	// asset.
	PortEndpoint PortType = "endpoint"
)

The closed set of port types.

type PortTypeInfo 

type PortTypeInfo struct {
	Type  PortType `json:"type"`
	Label string   `json:"label"`
	// Carries are the CTIS asset types a stream of this type holds; empty
	// for findings and endpoints, which are not assets.
	Carries []string `json:"carries"`
}

PortTypeInfo describes one port type.

func LookupPortType 

func LookupPortType(t PortType) (PortTypeInfo, bool)

LookupPortType returns a port type's description.

func PortTypes 

func PortTypes() []PortTypeInfo

PortTypes returns the closed port type set, in display order.

type Rule 

type Rule struct {
	Shape  string   `json:"shape,omitempty"`
	Select string   `json:"select"`
	Paths  []string `json:"paths,omitempty"`
	AnyOf  []string `json:"any_of,omitempty"`
}

Rule is a required-output rule: every record of a report that Select picks must carry every path in Paths and at least one path in AnyOf. A path is present when it holds a value other than null, "" or an empty list or object. A rule picking no record is satisfied (an empty result is a valid result).

Select is "assets", "findings", "dependencies" or "endpoints" (CTIS 1.6), the first two optionally with a type filter: "assets[type=open_port]", "assets[type=ip_address|host]", "findings[type=secret]". A path is dotted JSON member names relative to the record; "[]" after a member means the member is a list that must not be empty and the rest of the path applies to every element ("technical.domain.dns_records[].type").

Shape names one of several accepted output shapes of a capability. A tool that declares its shape is checked against the rules of that shape and the unnamed rules only.

type Status 

type Status string

Status is how far a capability is from being runnable. 

const (
	// StatusRouted: at least one built-in tool implements it.
	StatusRouted Status = "routed"
	// StatusPlanned: the contract is defined; no built-in implements it yet.
	StatusPlanned Status = "planned"
	// StatusLater: listed so the vocabulary is complete; not runnable, and
	// the contract may still change before the first implementation.
	StatusLater Status = "later"
)

Statuses.

type Violation 

type Violation struct {
	// Kind is "missing_path", "missing_any_of" or "not_allowed".
	Kind string `json:"kind"`
	// Record is the JSON pointer of the record ("/assets/3").
	Record string `json:"record"`
	// Path is the rule path that is missing, or the comma-joined any_of
	// list; for not_allowed, the output kind ("asset:certificate").
	Path string `json:"path"`
}

Violation is one way a report misses a capability's contract.

func (Violation) String 

func (v Violation) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.