IriusRisk

Threat Intelligence

Overview
Setup
Data & mappings
Operations & API
Changelog

The IriusRisk Connector integrates with the IriusRisk threat modeling platform to synchronize threat modeling data into Brinqa. It uses the IriusRisk API v2 to retrieve projects, components, threats, weaknesses, and countermeasures, and maps them onto the Brinqa Unified Data Model (UDM) as applications, packages, violations, and violation definitions.

Each sync performs a full retrieval of the configured object types. The connector does not apply incremental (since) filtering against the IriusRisk API — every sync walks all projects and their child resources.

Data retrieved from IriusRisk

Connector Object	Required	Maps to Data Model
Project	Yes	Application
Component	Yes	Package
Threat	Yes	Violation
Threat Definition	Yes	Violation Definition
Violation	Yes	Violation
Violation Definition	Yes	Violation Definition
Countermeasure	Yes	Countermeasure

Model relationships

note

For detailed steps on how to view the data retrieved from IriusRisk in the Brinqa Platform, see How to view your data.

Connection settings

When setting up a data integration, select IriusRisk from the Connector dropdown and provide the following:

Setting	Required	Default	Description
URL	Yes	—	IriusRisk URL
API token	Yes	—	IriusRisk API token
Maximum retries	No	`5`	The maximum number of retry attempts before giving up a request
Page size	No	`100`	Maximum number of records to get per API request
Include custom fields on Threat	No	`false`	Whether to include custom fields as attributes on the Threat model
Include custom fields on Project	No	`false`	Whether to include custom fields as attributes on the Project model
Parallel requests	No	`min(2, CPU cores)`	The maximum number of parallel API requests

Authentication

The connector uses API Token authentication. A single API token is sent as a custom api-token request header on every request. There is no token-exchange or login round-trip; the configured token is attached directly to each call.

Connectivity Test Endpoint

Method	URL
`GET`	`/api/v1/products`

Request Headers

Header	Value
`Content-Type`	`application/json`
`api-token`	`<your-api-token>`

Sample Response

A successful call to a paged v2 endpoint (e.g. /api/v2/projects) returns an HTTP 200 with a HAL-style envelope:

{
  "_embedded": {
    "items": [
      {
        "id": "2bbb99fa-af8a-6c22-6f02-ba4dc2ac8330",
        "name": "SAB ICIAPEX"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://<iriusrisk-url>/api/v2/projects?page=0&size=100"
    }
  },
  "page": {
    "size": 100,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}

Response Fields

Field	Description
`_embedded.items`	Array of resource objects for the current page
`_links.self.href`	Self link for the current page
`_links.next.href`	Link to the next page (present when more pages exist)
`page.size`	Requested page size
`page.totalElements`	Total number of matching records
`page.totalPages`	Total number of pages
`page.number`	Current (zero-based) page index

Token Usage

The token is read from the configured apiToken property and attached to every request as the api-token header. The same header is used for all subsequent paged requests; pagination is driven by the page and size query parameters and the presence of _links.next.

api-token: <your-api-token>
Content-Type: application/json

How to obtain IriusRisk credentials

Create read-only roles in IriusRisk

To ensure that the IriusRisk connector has the appropriate permissions to access and retrieve data from the IriusRisk API, it is recommended to create a dedicated API access and read-only roles in IriusRisk.

IriusRisk uses two role types:

Global roles: Provide system-wide permissions across all projects and business units.
Project roles: Apply to specific projects or business units and are automatically assigned when a user is added to a project.

The IriusRisk connector requires both role types. For additional information, see IriusRisk documentation on Assigning Global and Project Roles.

To create the read-only roles, follow these steps:

Log in to your IriusRisk portal as an administrator.
Navigate to Settings > User settings > Permissions.
Click the Global roles tab, and then click Create role.

The Create role dialog displays.
Provide a Name and Description, and then enable the following permissions:
- API_ACCESS
- COMPONENT_DEFINITION_VIEW
- PRODUCTS_LIST_ALL
Click Create.
Click the Project roles tab, and then click Create role.

The Create role dialog displays.
Provide a Name and Description, and then enable the following permissions:
- COUNTERMEASURE_VIEW
- THREAT_VIEW
Click Create.

Note: If you do not have permissions to create a new role, contact your IriusRisk administrator. For additional information, see IriusRisk documentation.

Assign the read-only roles to a new user

After creating the read-only roles, you can create a new IriusRisk user and assign those roles to the user. To do so, follow these steps:

Log in to your IriusRisk portal as an administrator.
Navigate to Settings > User settings > Users.
Click Create user.

The Create user dialog displays.
Provide a First name and Last name, Username, Email, and Password.
Click the Global roles dropdown and select the API access and read-only global role that you created earlier.
Click the Project roles dropdown and select the API access and read-only project role that you created earlier.
Click Create.

The new user displays in the list of users. The new user can now log in to the IriusRisk portal and generate an API token to use with the IriusRisk connector.

Note: If you do not have permissions to create a new user, contact your IriusRisk administrator. For additional information, see IriusRisk documentation.

Create an IriusRisk API token

For the IriusRisk connector to use the IriusRisk API, you must provide an API token. To obtain an API token, follow these steps:

Log in to your organization's IriusRisk portal as the dedicated read-only user.
Click the user profile in the upper-right corner of the page, and then select User profile from the dropdown.
Locate the Authentication section on the page, and then click Generate API token.

Your new API token displays. You can't view the token again after this. Copy and save it to a secure location.

Note: If you do not have permissions to create an API token, contact your IriusRisk administrator. For additional information, see IriusRisk documentation.

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Project

Source Field Name	SDM Attribute
constant ASSET_CATEGORY_PROJECT	CATEGORIES
sync time	LAST_CAPTURED
`customFields[]`	custom fields
`description`	DESCRIPTION
`id`	UID
`isArchived`	IS_ARCHIVED
`isBlueprint`	IS_BLUEPRINT
`isThreatModelLocked`	IS_THREAT_MODEL_LOCKED
`modelUpdated`	SOURCE_LAST_MODIFIED
`name`	NAME
`operation`	OPERATION
`readOnly`	READ_ONLY
`referenceId`	REFERENCE_ID
`state`	STATE
`state`	STATUS
`tags`	TAGS
`version.creationDate`	SOURCE_CREATED_DATE
`version.description`	VERSION_DESCRIPTION
`version.id`	VERSION_ID
`version.name`	VERSION_NAME
`workflowState.name`	WORKFLOW_STATE_NAME
`workflowState.referenceId`	WORKFLOW_STATE_REFERENCE_ID
`workflowState.uuid`	WORKFLOW_STATE_UUID

Component

Source Field Name	SDM Attribute
constant ASSET_CATEGORY_PACKAGE	CATEGORIES
sync time	LAST_CAPTURED
`componentDefinition.id`	COMPONENT_DEFINITION_ID
`componentDefinition.name`	COMPONENT_DEFINITION_NAME
`description`	DESCRIPTION
`diagramComponentId`	DIAGRAM_COMPONENT_ID
`id`	UID
`name`	NAME
`parent.id`	PARENT
`project.id`	PROJECT_ID
`project.name`	PROJECT_NAME
`project.name`	TARGETS
`referenceId`	REFERENCE_ID
`tags`	TAGS

Threat

Source Field Name	SDM Attribute
sync time	LAST_CAPTURED
`availability`	AVAILABILITY
`component.id`	COMPONENT_ID
`component.name`	COMPONENT_NAME
`confidentiality`	CONFIDENTIALITY
`easeOfExploitation`	EASE_OF_EXPLOITATION
`edited`	IS_EDITED
`effectiveMitigation`	EFFECTIVE_MITIGATION
`expiryDate`	EXPIRY_DATE
`id`	UID
`inherentRisk`	INHERENT_RISK
`integrity`	INTEGRITY
`issueId`	ISSUE_ID
`issueLink`	ISSUE_LINK
`issueState`	ISSUE_STATE
`library.id`	LIBRARY_ID
`library.name`	LIBRARY_NAME
`mitigation`	MITIGATION
`name`	NAME
`name`	TYPE
`owner.username`	OWNER
`project.id`	PROJECT_ID
`project.name`	PROJECT_NAME
`project.name, component.name`	TARGETS
`projectedRisk`	PROJECTED_RISK
`risk`	RISK
`risk (derived)`	SEVERITY_SCORE
`risk (normalized)`	SEVERITY
`state`	STATE
`state`	PROVIDER_STATUS
`state (categorized)`	STATUS_CATEGORY
`state (normalized)`	STATUS
`state (normalized)`	SOURCE_STATUS
`threat detail customFields[]`	custom fields

Threat Definition

Source Field Name	SDM Attribute
sync time	LAST_CAPTURED
`description`	DESCRIPTION
`name`	UID
`name`	NAME
`referenceId`	REFERENCE_ID
`referenceId`	TAGS
`source`	SOURCE
`useCase.id`	USE_CASE_ID
`useCase.name`	USE_CASE_NAME
`useCase.name`	CATEGORIES

Violation

Source Field Name	SDM Attribute
`_links.countermeasures.href`	COUNTERMEASURES
`_links.self.href`	LINK
sync time	LAST_CAPTURED
`component.id`	COMPONENT_ID
`component.name`	COMPONENT_NAME
`impact`	IMPACT
`issueId`	ISSUE_ID
`issueLink`	ISSUE_LINK
`issueState`	ISSUE_STATE
`issueState`	PROVIDER_STATUS
`issueState (normalized)`	SOURCE_STATUS
`MD5(referenceId/name/id + targets)`	UID
`name`	NAME
`parent threat.id`	THREAT_ID
`parent threat.name`	THREAT_NAME
`project.id`	PROJECT_ID
`project.name`	PROJECT_NAME
`project.name, component.name, threat name`	TARGETS
referenceId / name / id	TYPE
`test._links.self.href`	TEST_LINK
`test.id`	TEST

Violation Definition

Source Field Name	SDM Attribute
sync time	LAST_CAPTURED
`description`	DESCRIPTION
`referenceId`	REFERENCE_ID
`referenceId`	CWE_IDS
`referenceId`	WEAKNESSES
referenceId / name / id	UID
referenceId / name / id	NAME

Countermeasure

Source Field Name	SDM Attribute
sync time	LAST_CAPTURED
`component.id`	COMPONENT_ID
`component.name`	COMPONENT_NAME
`cost`	COST
`description`	DESCRIPTION
`edited`	EDITED
`id`	UID
`id`	COUNTERMEASURE_ID
`issueId`	ISSUE_ID
`issueLink`	ISSUE_LINK
`issueState`	ISSUE_STATE
`name`	NAME
`owner.username`	OWNER
`parent threat.id`	THREAT_ID
`priority.calculated`	PRIORITY_CALCULATED
`priority.manual`	PRIORITY_MANUAL
`project.id`	PROJECT_ID
`project.name`	PROJECT_NAME
`referenceId`	REFERENCE_ID
`risk`	RISK
`source`	SOURCE
`state`	STATE
`templateName`	TEMPLATE_NAME

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Project

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects

Component

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects/{projectId}/components

Threat

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects/{projectId}/threats

Threat Definition

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects/{projectId}/threats

Violation

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects/threats/{threatId}/weaknesses

Violation Definition

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects/threats/{threatId}/weaknesses

Countermeasure

Operation options

This object does not support any operation options.

Delta sync

Supported.

API

Type: REST endpoint · Endpoint: GET /api/v2/projects/threats/{threatId}/countermeasures

Changelog

The IriusRisk connector has undergone the following changes:

Version	Description	Migration Steps
3.0.7	Changed - Moved 13 threat instance-specific attributes from Threat Definition to Threat model - CIA attributes: Availability, Confidentiality, Integrity - Risk attributes: Inherent Risk, Risk, Projected Risk, Ease of Exploitation - Mitigation attributes: Mitigation, Effective Mitigation - Issue attributes: Edited, Issue ID, Issue Link, Issue State - Moved SEVERITY and SEVERITY_SCORE from Threat Definition to Threat model - Moved `source` attribute from Threat to Threat Definition (findingDefinition) - Moved `normalizeThreatSeverity()` to BaseThreat for shared access Added - `LAST_CAPTURED` to Threat, Threat Definition, Project, and Component models - `SOURCE_STATUS` to Threat model (normalized from `state`) - `CATEGORIES` to Threat Definition (mapped from `useCase.name`) - Updated README.md with new attribute mapping tables - Added test resource JSON files for Component and ThreatDefinition	N/A
3.0.7	New Features - Weakness Synchronization: Added support for synchronizing weaknesses as `Violation` and `Violation Definition` objects using the IriusRisk API v2. - Parallel Processing: Implemented parallel processing for fetching weaknesses to improve performance, with a configurable parallelism level. Improvements - Enhanced Project and Threat Models: Updated `Project` and `Threat` models to support fetching and mapping custom fields independently. - Improved API Resource Handling: Introduced `WeaknessResource` and updated existing resources to better handle IriusRisk API v2 responses.	N/A

Data retrieved from IriusRisk​

Model relationships​

Connection settings​

Authentication​

Connectivity Test Endpoint​

Request Headers​

Sample Response​

Response Fields​

Token Usage​

Create read-only roles in IriusRisk​

Assign the read-only roles to a new user​

Create an IriusRisk API token​

Attribute mappings​

Operations & API​

Changelog​

Data retrieved from IriusRisk

Model relationships

Connection settings

Authentication

Connectivity Test Endpoint

Request Headers

Sample Response

Response Fields

Token Usage

Create read-only roles in IriusRisk

Assign the read-only roles to a new user

Create an IriusRisk API token

Attribute mappings

Operations & API

Changelog