REST Resource: projects.findings

Resource: Finding

A ‘stateless’ and a point in time event that a check produced a result of interest.

JSON representation 
{
  "name": string,
  "asset": string,
  "issue": string,
  "provider": string,
  "displayName": string,
  "detail": {
    object (FindingDetail)
  },
  "severity": number,
  "reoccurrenceTimes": [
    string
  ],
  "relevanceAnalysis": {
    object (RelevanceAnalysis)
  },
  "severityAnalysis": {
    object (SeverityAnalysis)
  },
  "aiSummary": string,
  "audit": {
    object (Audit)
  },
  "alert": string,
  "configurations": [
    string
  ]
}
Fields
name

string

Identifier. Server generated name for the finding (leave clear during creation). Format: projects/{project}/findings/{finding}
asset

string

Optional. Optional - asset name if known. Format: projects/{project}/assets/{asset}
issue

string

Optional. Optional - name of the issue that this finding is bound to. Format: projects/{project}/issues/{issue}
provider

string

Required. Logical source of this finding (name of the sub-engine).
displayName

string

Required. A short descriptive title for the finding <= 250 chars. EX: "Actor 'baddy' offering $1000 for credentials of 'goodguy'".
detail

object (FindingDetail)

Required. Holder of the domain specific details of the finding.
severity
(deprecated)

number

Optional. Deprecated: Use the severityAnalysis field instead. Base severity score from the finding source.
reoccurrenceTimes[]

string (Timestamp format)

Output only. When identical finding (same labels and same details) has re-occurred.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
relevanceAnalysis

object (RelevanceAnalysis)

Output only. High-Precision Relevance Analysis verdict for the finding.
severityAnalysis

object (SeverityAnalysis)

Output only. High-Precision Severity Analysis verdict for the finding.
aiSummary

string

Optional. AI summary of the finding.
audit

object (Audit)

Output only. Audit data about the finding.
alert

string

Optional. Name of the alert that this finding is bound to.
configurations[]

string

Optional. Configuration names that are bound to this finding.

FindingDetail

Wrapper class that contains the union struct for all the various findings detail specific classes.

JSON representation 
{
  "detailType": string,

  // Union field detail can be only one of the following:
  "inbandVulnerability": {
    object (InbandVulnerabilityFindingDetail)
  },
  "misconfiguration": {
    object (MisconfigurationFindingDetail)
  },
  "initialAccessBroker": {
    object (InitialAccessBrokerFindingDetail)
  },
  "dataLeak": {
    object (DataLeakFindingDetail)
  },
  "insiderThreat": {
    object (InsiderThreatFindingDetail)
  },
  "targetTechnology": {
    object (TargetTechnologyFindingDetail)
  }
  // End of list of possible types for union field detail.
}
Fields
detailType

string

Output only. Name of the detail type. Will be set by the server during creation to the name of the field that is set in the detail union.
Union field detail. Domain specific details object which includes a high level summary of the finding for use in ATD contexts. detail can be only one of the following:
inbandVulnerability

object (InbandVulnerabilityFindingDetail)

Inband vulnerability detail type.
misconfiguration

object (MisconfigurationFindingDetail)

Misconfiguration finding detail type.
initialAccessBroker

object (InitialAccessBrokerFindingDetail)

Initial Access Broker finding detail type.
dataLeak

object (DataLeakFindingDetail)

Data Leak finding detail type.
insiderThreat

object (InsiderThreatFindingDetail)

Insider Threat finding detail type.
targetTechnology

object (TargetTechnologyFindingDetail)

Technology Watchlist finding detail type.

InbandVulnerabilityFindingDetail

This is a temporary detail type that will be used to support vulnerabilities until the engines start using the full vulnerability objects. The "Inband" refers to the fact that all vulnerability details are included with every finding.

JSON representation 
{
  "vulnerability": {
    object (InbandVulnerability)
  },
  "requestUri": string,
  "formattedProofDetails": string
}
Fields
vulnerability

object (InbandVulnerability)

Required. Vulnerability metadata.
requestUri

string

Optional. The URI that lead to this detection, if appropriate.
formattedProofDetails

string

Optional. A short description of the proof of the vulnerability.

InbandVulnerability

Fleshed out vulnerability object that includes enough details to fill out a vulnerability specific view for an issue.

JSON representation 
{
  "externalVulnerabilityId": string,
  "cveId": string,
  "cvssV31Score": number,
  "title": string,
  "description": string,
  "remediation": string,
  "affectedSoftware": [
    {
      object (AffectedSoftware)
    }
  ],
  "referenceUrls": [
    string
  ],
  "authors": [
    string
  ],
  "riskRating": string,
  "exploitationState": string,
  "isExploitedWild": boolean,
  "cvssV31ScoreTemporal": number,
  "disclosureTime": string
}
Fields
externalVulnerabilityId

string

Required. The external ID of the vulnerability.
cveId

string

Required. The CVE ID of the vulnerability.
cvssV31Score

number

Required. The CVSS V3.1 score (Base score)for the vulnerability. ( )
title

string

Optional. Human readable name for the vulnerability.
description

string

Optional. The human readable description. This can be basic HTML formatted text.
remediation

string

Optional. The human readable remediation recommendation. This can be basic HTML formatted text.
affectedSoftware[]

object (AffectedSoftware)

Optional. The software that is affected by the vulnerability.
referenceUrls[]

string

Optional. Reference URLs to the vulnerability.
authors[]

string

Optional. The authors of the vulnerability detection.
riskRating

string

Optional. Risk rating for the vulnerability, for example "High".
exploitationState

string

Optional. Exploitation state of the vulnerability, for example "Available".
isExploitedWild

boolean

Optional. Whether this is exploited in the wild.
cvssV31ScoreTemporal

number

Optional. Temporal CVSS V3.1 score for the vulnerability.
disclosureTime

string (Timestamp format)

Optional. The date the vulnerability was first disclosed.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

AffectedSoftware

The software that is affected by the vulnerability.

JSON representation 
{
  "vendor": string,
  "product": string
}
Fields
vendor

string

Optional. The vendor of the software.
product

string

Optional. The product of the software.

MisconfigurationFindingDetail

Misconfiguration finding detail.

JSON representation 
{
  "misconfigurationMetadata": {
    object (MisconfigurationMetadata)
  }
}
Fields
misconfigurationMetadata

object (MisconfigurationMetadata)

Required. The misconfiguration metadata.

MisconfigurationMetadata

Misconfiguration metadata.

JSON representation 
{
  "misconfigurationId": string,
  "vulnerableUri": string,
  "description": string,
  "displayName": string,
  "remediation": string,
  "references": [
    {
      object (MisconfigurationReference)
    }
  ]
}
Fields
misconfigurationId

string

Required. The identifier for the misconfiguration. This is an internal name generated by the finding provider.
vulnerableUri

string

Optional. The endpoint which was found to have the vulnerability.
description

string

Optional. Description of the misconfiguration.
displayName

string

Optional. A user-friendly name for the misconfiguration.
remediation

string

Optional. Recommended remediation steps for the misconfiguration.
references[]

object (MisconfigurationReference)

Optional. References to external resources that provide more information about the misconfiguration.

MisconfigurationReference

A reference to an external resource that provides more information about a misconfiguration.

JSON representation 
{
  "uri": string,
  "type": string
}
Fields
uri

string

Required. The URI of the reference.
type

string

Required. The type of the reference (e.g., "description", "remediation").

InitialAccessBrokerFindingDetail

A detail object for an Initial Access Broker (IAB) finding.

JSON representation 
{
  "matchScore": number,
  "severity": enum (Severity),
  "documentId": string
}
Fields
matchScore

number

Required. Reference to the match score of the IAB finding. This is a float value between 0 and 1 calculated by the matching engine based on the similarity of the document and the user provided configurations.
severity

enum (Severity)

Required. The severity of the IAB finding. This indicates the potential impact of the threat.
documentId

string

Required. The unique identifier of the document that triggered the IAB finding. This ID can be used to retrieve the content of the document for further analysis.

Severity

Severity of the threat finding

Enums
SEVERITY_UNSPECIFIED
LOW
MEDIUM
HIGH
CRITICAL

DataLeakFindingDetail

A detail object for a Data Leak finding.

JSON representation 
{
  "matchScore": number,
  "severity": enum (Severity),
  "documentId": string
}
Fields
matchScore

number

Required. Reference to the match score of the Data Leak finding. This is a float value greater than 0 and less than or equal to 1 calculated by the matching engine based on the similarity of the document and the user provided configurations.
severity

enum (Severity)

Required. The severity of the Data Leak finding. This indicates the potential impact of the threat.
documentId

string

Required. The unique identifier of the document that triggered the Data Leak finding. This ID can be used to retrieve the content of the document for further analysis.

Severity

Severity of the threat finding.

Enums
SEVERITY_UNSPECIFIED Default value, should never be set.
LOW Low severity.
MEDIUM Medium severity.
HIGH High severity.
CRITICAL Critical severity.

InsiderThreatFindingDetail

A detail object for a InsiderThreat finding.

JSON representation 
{
  "matchScore": number,
  "severity": enum (Severity),
  "documentId": string
}
Fields
matchScore

number

Required. Reference to the match score of the InsiderThreat finding. This is a float value greater than 0 and less than or equal to 1 calculated by the matching engine based on the similarity of the document and the user provided configurations.
severity

enum (Severity)

Required. The severity of the InsiderThreat finding. This indicates the potential impact of the threat.
documentId

string

Required. The unique identifier of the document that triggered the InsiderThreat finding. This ID can be used to retrieve the content of the document for further analysis.

Severity

Severity of the threat finding.

Enums
SEVERITY_UNSPECIFIED Default value, should never be set.
LOW Low severity.
MEDIUM Medium severity.
HIGH High severity.
CRITICAL Critical severity.

TargetTechnologyFindingDetail

Contains details for a technology watchlist finding.

JSON representation 
{
  "vulnerabilityMatch": {
    object (VulnerabilityMatch)
  }
}
Fields
vulnerabilityMatch

object (VulnerabilityMatch)

Output only. The vulnerability match details.

Methods

get

 Get a finding by name.

list

 Get a list of findings that meet the filter criteria.
SearchFindings is a more powerful version of ListFindings that supports complex queries like "findings for issues" using functions such as has_issue and has_asset in the query string.