Skip to main content

Finding

Struct Finding 

Source
pub struct Finding { /* private fields */ }
Expand description

One thing wrong with a scanned subject: a typed, provenance-tagged claim.

Every finding names the DetectionId that produced it, carries two independent judgements (Severity and Confidence), holds a bounded Excerpt of the bytes that justify it, and points at zero or more typed References. Built through Finding::new and the with_* builders, so every finding passes the same checks whether scanned, rebuilt from a file, or returned by a module.

Implementations§

Source§

impl Finding

Source

pub fn new( detection: DetectionId, title: impl Into<String>, severity: Severity, confidence: Confidence, class: DetectionClass, ) -> Result<Self, FindingError>

A finding from its required parts, or FindingError::EmptyTitle if title is blank.

The excerpt, references and remediation start empty and are added with the builders below.

Source

pub fn with_reference(self, reference: Reference) -> Self

Adds a reference, keeping the order they arrive in. A duplicate folds away, so two runs that found the same references write the same file.

Source

pub fn with_excerpt(self, excerpt: Excerpt) -> Self

Sets the justifying excerpt. Already bounded by Excerpt::new.

Source

pub fn with_remediation(self, remediation: impl Into<String>) -> Self

Sets the remediation advice.

Source

pub fn with_cpe(self, cpe: impl Into<String>) -> Self

Adds a platform identifier the finding was drawn from.

For a correlation, which draws a finding from a CPE a service carries. Adding one already named changes nothing.

Source

pub fn with_subject(self, subject: impl Into<String>) -> Self

Names what the claim is about, which claim_id then keys on in place of the references.

For a detection whose findings summarise a changing set of references, as a correlation’s do, so the claim does not rename itself when the data changes.

Source

pub fn with_build(self, build: Build) -> Self

Records the distribution build a correlation judged.

Source

pub fn with_advised_by(self, advised_by: DetectionId) -> Self

Records the distributor’s advisory data a correlation consulted.

Source

pub fn with_exploitation(self, exploitation: Exploitation) -> Self

Records which of the vulnerabilities it cites are known to be exploited.

Source

pub fn with_group(self, group: FindingGroup) -> Self

Records which group of findings this one belongs to.

Source

pub fn group(&self) -> Option<&FindingGroup>

What this finding is one of, where its detection declared a group.

Source

pub fn subject(&self) -> Option<&str>

What the claim is about, where the detection named it. Untrusted.

Source

pub fn build(&self) -> Option<&Build>

The distribution build a correlation judged, if it judged one.

Source

pub fn advised_by(&self) -> Option<&DetectionId>

The distributor’s advisory data a correlation consulted, if any.

Source

pub fn exploitation(&self) -> Option<&Exploitation>

Which of the vulnerabilities it cites are known to be exploited, if a list consulted names any.

Source

pub fn detection(&self) -> &DetectionId

The detection that produced this finding.

Source

pub fn title(&self) -> &str

The one-line title. Untrusted; escape before display.

Source

pub fn severity(&self) -> Severity

How bad this finding is if true.

Source

pub fn confidence(&self) -> Confidence

How sure this finding is true.

Source

pub fn class(&self) -> DetectionClass

The intrusiveness the producing detection ran under.

Source

pub fn excerpt(&self) -> &Excerpt

The bytes that justify this finding.

Source

pub fn references(&self) -> impl Iterator<Item = &Reference>

The external references, in the order the detection stated them, which is most-relevant-first where it had an order to state.

Source

pub fn remediation(&self) -> Option<&str>

The remediation advice, if any. Untrusted; escape before display.

Source

pub fn cpes(&self) -> impl Iterator<Item = &str>

The platform identifiers a correlation drew this finding from, ascending, and none for a finding drawn from anything else. Untrusted: a scanned host’s banner chose them, so escape before display.

Each draws the same claim, so it stands while any of them still identifies the endpoint.

Source

pub fn claim_id(&self) -> ClaimId

The key that decides whether this finding and another are the same claim.

The producing detection’s id, paired with the subject it discriminates on: the subject the detection named where it named one, otherwise the lowest CVE identifier this finding references, or its title where it references none.

The lowest, not the first: a correlation states its worst first, which changes when the catalogue does, so keying on the first would rename the claim after a data refresh and a diff of an unchanged host would show one finding gone and another arrived.

Source

pub fn corroborate(&mut self, other: Finding) -> bool

Folds another account of the same claim into this one, keeping the stronger reading, and reports whether anything changed.

Called when a detection asserts a claim a subject already carries: the same producer and claim_id. The caller must have matched the claims.

The verdict (severity, title, class) follows the version, so it stays in step with the DetectionId that records who concluded it:

  • An account at a lower version supplies only what is missing. Otherwise folding a 1.0.0 reading into a 2.0.0 one would leave 2.0.0 stamped on 1.0.0’s Low. This is the common direction, since the record folded in is usually the older.
  • An account at the same version supplies the verdict: one detection grading a claim differently twice has read different evidence, and the later reading wins. merge folds documents in the order their own clocks give, so a cipher Low in January and Critical in June is Critical.
  • A newer version supplies the verdict and its own stamp.

Regardless of version, certainty only rises, since a second agreeing account is worth something whichever build produced it, and references and platform identifiers union, as Service::merge unions CPEs. Keeping one identifier would have a merge drop the claim once a newer scan backed only the other.

Except for correlations, whose certainty and references are part of the verdict. A correlation is a computation over a service identification and the datasets behind it, and a later one that cites fewer vulnerabilities, or holds them less surely, has usually learned some do not apply to this build. Unioning would carry every vulnerability ever cited into every later report at the surest grade ever given. So an account of a correlation at the same version or newer replaces the certainty, references, build, advisory stamp and exploitation outright, and an older one supplies none of them.

The excerpt and remediation travel with the verdict where one is taken, and otherwise fill a gap.

Trait Implementations§

Source§

impl Clone for Finding

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Finding

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Eq for Finding

Source§

impl From<&Finding> for FindingRecord

Source§

fn from(finding: &Finding) -> Self

Converts to this type from the input type.
Source§

impl PartialEq for Finding

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for Finding

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

Source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

Source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

Source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more