What comes back

Part of the API reference. Authentication, scopes, rate limits and errors are on the overview.

BitHive Reporting Desk API · 0.11.0

What comes back

`ContractState`

Parameter	Type	Description
`id` required	string (uuid)
`kind` required	string	notice_clause for a customer's notice clause, gdpr_controller for a controller the account processes personal data for.
`counterparty` required	string
`archived_at` required	string,null (date-time)	When the contract was archived; null while it is in use.

`Product`

Parameter	Type	Description
`id` required	string (uuid)
`name` required	string
`created_at` required	string (date-time)
`archived` required	boolean	An archived product is no longer monitored.

`ProductList`

Parameter	Type	Description
`products` required	array of object

`SBOM`

Parameter	Type	Description
`id` required	string (uuid)
`product_id` required	string (uuid)
`format` required	string
`spec_version` required	string	Version of the specification the document follows, for example 1.6 or SPDX-2.3.
`sha256` required	string	SHA-256 of the stored document, in lower-case hexadecimal. It addresses the document.
`component_count` required	integer	Components the document listed, after repetitions were dropped.
`source` required	string	Whether the upload came through the interface or this API.
`created_at` required	string (date-time)
`release`	string	The release the document describes. Absent when nobody named it and the document gave none.
`on_market` required	boolean	The release is on the market, so it stays monitored after newer uploads.
`monitored` required	boolean	Matching and cases follow this upload, because it is on the market or it is the product's latest.
`on_market_refused`	boolean	Only in the answer to an upload: on_market=true was asked while the product already had 25 releases on the market. The document is stored all the same, and monitored while it is the latest upload.
`generated_from`	array of string	Only for a document the Reporting Desk wrote from lockfiles or manifests (API 0.9.0): the names of the files, without their directories.
`partial`	boolean	Only for a document the Reporting Desk wrote, and only when true: the files list only part of what the build uses (a pom.xml names no transitive dependency, nor need a requirements.txt without a `--hash` on every pinned line, and a go.mod for a Go before 1.17 names only the direct ones), so the components not in the document are not monitored.
`left_out`	integer	Only for a partial document the Reporting Desk wrote: how many dependencies the files named without an exact version, and so left out.

`ReleaseChange`

Parameter	Type	Description
`release`	string	The release's new name; an empty string removes it.
`on_market`	boolean	True puts the release on the market, false takes it off.

`SBOMList`

Parameter	Type	Description
`sboms` required	array of object

`Component`

Parameter	Type	Description
`name` required	string
`version` required	string	Empty when the document stated no version; such a component cannot be matched.
`purl` required	string	Package URL as the document carried it, empty when it carried none.

`ComponentList`

Parameter	Type	Description
`components` required	array of object
`total` required	integer

`Finding`

Parameter	Type	Description
`id` required	string (uuid)
`component` required	object
`vulnerability` required	object
`evidence` required	string	Whether the feed stated the affected version outright, or the version was compared against a published range; `cpe` when a component without a matched package URL was matched by its CPE name and NVD's affected versions, so the build may carry a backported fix; `check` when its CPE names no vendor and it was matched on the product alone, which raises no case or alert until a person confirms the vendor in the interface.
`matched_range`	string	The range that decided a compared match.
`state` required	string
`exploited` required	boolean	The vulnerability is known to be exploited, which starts the 24-hour report.
`exploited_cve`	string	The identifier the exploitation catalogue lists it under.
`exploited_since`	string (date)	The day the catalogue added it.
`ransomware` required	boolean	The catalogue has linked it to a ransomware campaign.
`first_seen_at` required	string (date-time)	When the Reporting Desk first saw this finding. Reporting deadlines are measured from our own knowledge.
`last_seen_at` required	string (date-time)
`sbom_id` required	string (uuid)	The monitored upload the finding was made in.
`release`	string	The release that upload describes. Absent when nobody named it.
`decision`	object	The current statement about the release and the vulnerability. Absent when none is current or the release has no name.

`Decision`

Parameter	Type	Description
`id` required	string (uuid)
`release` required	string
`vulnerability` required	string	The vulnerability's identifier, as the findings name it.
`status` required	string
`justification`	string	Why the release is not affected; for not_affected only.
`impact_statement`	string	Why the release is not affected, in the account's words; for not_affected only.
`action_category`	string	The remediation; for affected only.
`action_statement`	string	What the account's customers should do; for affected only.
`decided_at` required	string (date-time)
`supersedes`	string (uuid)	The statement this one replaced, absent for the first of its release and vulnerability.
`finding_id`	string (uuid)	The finding it was made on, absent once matching replaced that finding or when made through the API.
`stale` required	boolean	The advisory changed after the statement was made, or a component was matched after it. The statement stays current until somebody decides again.

`DecisionList`

Parameter	Type	Description
`decisions` required	array of object

`NewDecision`

Parameter	Type	Description
`releases` required	array of string	The named releases the statement is about; one statement is written for each.
`vulnerability` required	string
`status` required	string
`justification`	string
`impact_statement`	string
`action_category`	string
`action_statement`	string

`FindingList`

Parameter	Type	Description
`findings` required	array of object
`total` required	integer
`exploited` required	integer	How many of them start a reporting deadline.

`NotMonitoredGroup`

Parameter	Type	Description
`reason` required	string
`ecosystem`	string	The ecosystem, when the reason is about one, so a client can see that it is Alpine rather than only that something is unsupported.
`explanation`	string	What specifically is unsolved. For "version could not be read": these versions cannot be ordered, so they are not checked against advisories that give a range of affected versions; they are still matched against advisories that list their exact version, which means such a component can have findings and still be counted here as not monitored.
`components` required	integer

`Coverage`

Parameter	Type	Description
`sbom_id`	string (uuid)	The upload this describes; absent when the product has none.
`components` required	integer
`monitored` required	integer
`monitored_percent` required	number	The monitored share, rounded to one decimal place.
`not_monitored` required	array of object

`CaseList`

Parameter	Type	Description
`cases` required	array of object
`next_cursor` required	stringnull	Sent as `cursor`, reads the next page; null on the last.

`CaseSummary`

A CRA case as a list shows it.

Parameter	Type	Description
`id` required	string (uuid)
`type` required	string	The trigger of Article 14, paragraph 1 or 3.
`state` required	string	How far the case has come: open, each stage recorded as submitted in turn, closed after the final report, or dismissed.
`product_id` required	string (uuid)
`cve` required	stringnull	The CVE the exploitation catalogue lists, or the one entered with the case.
`euvd_id` required	stringnull	The EU Vulnerability Database's identifier entered with the case.
`advisory_id` required	stringnull	The advisory the product's components were matched against.
`detected_at` required	string (date-time)	When the case was recorded. Never changes.
`became_aware_at` required	string (date-time)	When the manufacturer became aware, which the 24- and 72-hour deadlines count from.
`next_deadline` required	object or null	The stage whose stored deadline comes next and is not met; null when the case has no open deadline: always when the case is closed or dismissed, and also while it is still running but the next report's clock has not started, for example a vulnerability's final report before `fix_available_at` is recorded. null does not mean that no report is owed; read the case's state for that.

`CaseDueStage`

Parameter	Type	Description
`stage` required	string
`due_at` required	string (date-time)

`Case`

A CRA case with its stored deadlines and the state of each stage's report.

Parameter	Type	Description
`id` required	string (uuid)
`type` required	string
`state` required	string
`product_id` required	string (uuid)
`cve` required	stringnull
`euvd_id` required	stringnull
`advisory_id` required	stringnull
`detected_at` required	string (date-time)
`became_aware_at` required	string (date-time)
`next_deadline` required	object or null	The stage whose stored deadline comes next and is not met; null when the case has no open deadline: always when the case is closed or dismissed, and also while it is still running but the next report's clock has not started, for example a vulnerability's final report before `fix_available_at` is recorded. null does not mean that no report is owed; read the case's state for that.
`first_notified_at` required	string,null (date-time)	The first successful delivery of an alert about the case; null while none arrived.
`first_acknowledged_at` required	string,null (date-time)	When a person first took the case up.
`fix_available_at` required	string,null (date-time)	When a corrective or mitigating measure became available, which a vulnerability's final report counts from.
`occurred_at` required	string,null (date-time)	When a severe incident occurred, as the manufacturer stated it.
`deadlines` required	array of object	The stored deadlines, in the order they fall due. A stage that waits for its moment has none yet.
`reports` required	array of object	Each stage's report, early warning, notification and final report in that order.

`CaseDeadline`

Parameter	Type	Description
`stage` required	string
`due_at` required	string (date-time)
`basis` required	string	The moment the deadline is counted from.
`basis_at` required	string (date-time)
`met_at` required	string,null (date-time)	When the stage's report was submitted, as recorded; null until then.
`on_time` required	booleannull	Whether the stage's report was submitted by `due_at`: true when `met_at` is not after it, null until a report is recorded. It compares the two times as BitHive holds them. `due_at` is counted from the moment the stage's clock starts: the moment of awareness for the early warning and the notification, `fix_available_at` for a vulnerability's final report, and the recorded submission of the notification for a severe incident's final report. Changing that moment moves `due_at` and can change `on_time`. It says nothing else about the obligation.
`rule` required	string	The rule that computed the deadline; empty on a deadline an earlier release wrote, until it is given its rule.
`rule_version` required	integer

`CaseReport`

Parameter	Type	Description
`stage` required	string
`state` required	string	none, a draft is saved, or recorded as submitted.
`submitted_at` required	string,null (date-time)	When the report was submitted on ENISA's platform, as recorded.
`recorded_at` required	string,null (date-time)	When it was marked submitted in the Reporting Desk.

`RecordList`

Parameter	Type	Description
`records` required	array of object

`RecordSummary`

An incident record as a list shows it, with its nearest running deadline.

Parameter	Type	Description
`id` required	string (uuid)
`summary` required	string
`state` required	string	The case state, open until the record is closed.
`entered_at` required	string (date-time)
`aware_at` required	string (date-time)
`occurred_at` required	string,null (date-time)
`regimes` required	array of string
`next_deadline` required	object or null

`NextDeadline`

Parameter	Type	Description
`obligation` required	string
`stage` required	string
`due_at` required	string (date-time)
`overdue` required	boolean

`Record`

An incident record with the obligations the token's creator sees.

Parameter	Type	Description
`id` required	string (uuid)
`summary` required	string
`state` required	string
`entered_at` required	string (date-time)
`aware_at` required	string (date-time)
`occurred_at` required	string,null (date-time)
`regimes` required	array of string
`next_deadline` required	object or null
`detail` required	string
`definitions` required	array of string
`answers` required	object
`items` required	array of object
`obligations` required	array of object

`RecordItem`

Parameter	Type	Description
`kind` required	string
`name` required	string

`Obligation`

One obligation of a module on a record, keyed by its type and its party.

Parameter	Type	Description
`key` required	string
`regime` required	string
`type` required	string
`party` required	object
`party_name` required	string
`applicability` required	string
`suggested` required	string
`reason` required	string
`decided_by` required	string
`decided_at` required	string (date-time)
`stages` required	array of object

`ObligationParty`

Parameter	Type	Description
`kind` required	string
`id`	string (uuid)

`RecordStage`

A stage and its stored deadline, or the moment it waits for; closed by an answer.

Parameter	Type	Description
`id` required	string
`closed` required	boolean
`due_at` required	string,null (date-time)
`met_at` required	string,null (date-time)
`rule` required	string
`rule_version` required	integer
`waiting_for` required	string

`NewRecord`

What is stated when an incident is recorded.

Parameter	Type	Description
`summary` required	string
`detail`	string
`aware_at` required	string (date-time)
`occurred_at`	string,null (date-time)
`definitions` required	array of string
`legal_entities`	array of string (uuid)
`contracts`	array of string (uuid)
`member_states`	array of string
`services`	array of string
`answers`	object

`NewSubmission`

A stage's report as submitted, with where it went.

Parameter	Type	Description
`obligation` required	string
`stage` required	string
`language` required	string
`values` required	object
`submitted_at` required	string (date-time)
`submitted_by` required	string
`reference`	string
`sent` required	object	The channel it went over, by recipient.
`not_sent_reason`	string

`Submission`

The submission copy of a stage's report.

Parameter	Type	Description
`record` required	string (uuid)
`obligation` required	string
`stage` required	string
`submitted_at` required	string (date-time)
`recorded_at` required	string (date-time)
`submitted_by` required	string
`reference` required	string
`channel` required	string
`recipient` required	string
`sent` required	array of object
`not_sent` required	array of string
`template` required	string
`template_version` required	integer
`language` required	string
`sha256` required	string

`SubmissionSent`

Parameter	Type	Description
`recipient` required	string
`channel` required	string

`Problem`

RFC 9457 problem details.

Parameter	Type	Description
`type` required	string
`title` required	string
`status` required	integer
`detail`	string

The contract itself. This page is built from the OpenAPI document of the service. It is published as a file, so a client generator can read the same contract this page describes. Download openapi.yaml

Docs

Start free 14-day trial