Platform API - Extended Information

This document provides a detailed guide on using our API to import data into the Platform. Follow the outlined steps and use the provided endpoints to efficiently create and manage projects, phases, hosts, issues, and other entities.

Platform Workflow

The following details the workflow and elements required in the platform to receive data.

Steps to Import Data

1. Create a Project

2. Create a Phase/Scan

3. Create Hosts for the Phase/Scan

4. Create Issues for the Phase/Scan with the Hosts

5. Publish the Issues

API Endpoints and Usage

User Management

List Users

• Endpoint: [GET] /v1/api/users

• Description: Retrieve a list of existing users in the Platform. Use the user_id to assign entities like projects, phases, and assets to specific users.

Company Management

List Companies

• Endpoint: [GET] /v1/api/companies

• Description: Get a list of current companies. Use the company_id to assign projects and determine the test company performing scans.

Project Management

Create Project

• Endpoint: [POST] /v1/api/projects

• Description: Create a new project to house phases and issues.

• Payload Example:

  { "name": "string", "company_id": "int", "test_company_id": "int", "job_number": "string", "status": "int", "service_type": "int" }

  Additional Endpoints:

  • Project Statuses: [GET] /v1/api/projects/statuses

  • Project Service Types: [GET] /v1/api/projects/service-types

Create Phase/Scan

• Endpoint: [POST] /v1/api/phases

• Description: Create a phase/scan within a project to import issues.

• Payload Example:

  { "project_id": "int", "name": "string", "test_type_id" => "int", "status" => "int", "tags" => array([ "id" => "int" ]), "project_id" => "int" }

Host Management

Create Hosts

• Endpoint: [POST] /v1/api/phases/{phaseId}/hosts

• Description: Create hosts within a phase/scan.

• Payload Example:

  { "ip": "string", "hostname": "string", "name": "string", "location": "string", "operating_system": "string" }

Issue Management

Create Issue

• Endpoint: [POST] /v1/api/phases/{phaseId}/issues

• Description: Create issues to specify vulnerabilities and link them with hosts.

• Payload Example:

  { "name": "string", "cvss_vector": "string", "cvss_base_score": "int", "cvss_temporal_score": "int", "cvss_environmental_score": "int", "finding": "string", "references": "string", "summary": "string", "technical_details": "string", "recommendation": "string", "risk_rating": 2, "status": "IssueStatus", "confirmed_at": "2024-04-23 14:16:32", "published_at": "2024-04-23 14:16:32", "exploit_available": false, "active_exploit": false }

   

Attach Affected Instances During Issue Creation

• Endpoint: [POST] /v1/api/phases/{phaseId}/issues

• Description: Add additional affected instance information to the issue.

• Payload Example:

  { "name": "string", "cvss_vector": "string", "cvss_base_score": "string", "cvss_temporal_score": "string", "cvss_environmental_score": "string", "finding": "string", "references": "string", "summary": "string", "technical_details": "string", "recommendation": "string", "risk_rating": 2, "status": "IssueStatus", "confirmed_at": "2024-04-23 14:16:32", "published_at": "2024-04-23 14:16:32", "exploit_available": false, "active_exploit": false, "hosts": [ { "host_id": "int", "host_issues": [ { "port": 8080, "protocol": "TCP" }, { "port": 9090, "protocol": "UDP" } ] } ] }

   

Attach Affected Instances After Issue Creation

• Endpoint: [POST] /v1/api/phases/{phaseId}/issues/{issueId}/affected-instances

• Description: Attach affected instances to issues after their creation.

• Payload Example:

  { "host_id": "int", "port": 8080, "protocol": "TCP" }

   

Publish Issues

• Endpoint: [PUT] /v1/api/phases/{phaseId}/issues/{issueId}

• Description: Update the status of an issue to publish it.

• Payload Example:

  { "status": 9 }

Tag Management

List Tags

• Endpoint: [GET] /v1/api/tags

• Description: Retrieve existing tags in the Platform.

Create Tag

• Endpoint: [POST] /v1/api/tags

• Description: Create a new tag.

• Payload Example:

  { "name": "string" }

   

Update Tag

• Endpoint: [PUT] /v1/api/tags/{tagId}

• Description: Update an existing tag.

• Payload Example:

  { "name": "string" }

   

Attach Tags

• Tag Projects: [PUT] /v1/api/projects/{projectId}/tags/{tagId}

• Tag Phases: [PUT] /v1/api/phases/{phaseId}/tags/{tagId}

• Tag Assets: [PUT] /v1/api/assets/{assetId}/tags/{tagId}

Asset Management

Create Asset Group

• Endpoint: [POST] /v1/api/asset-groups

• Description: Create a new asset group.

• Payload Example:

  { "name": "string", "description": "string", "merge_setting_id": "int", "assets": [0] }

   

Assign Assets to Groups

• Endpoint: [PUT] /v1/api/asset-groups/{assetGroupId}/assets/sync

• Description: Assign assets to an asset group.

• Payload Example:

  { "asset_ids": [0] }

Comment Management

Create Issue Comment

• Endpoint: [POST] /v1/api/phases/{phaseId}/issues/{issueId}/comments

• Description: Add a comment to an existing issue.

• Payload Example:

  { "comment": "string" }

   

Create Project Comment

• Endpoint: [POST] /v1/api/projects/{projectId}/comments

• Description: Add a comment to an existing project.

• Payload Example:

  { "comment": "string" }

Asset Merge Settings

List Merge Settings

• Endpoint: [GET] /v1/api/merge-settings

• Description: Retrieve current asset merge settings.

• Response Example:

  { "data": [ { "value": 1, "title": "Merge Setting Title", "description": "Description of the merge setting" } ] }

Status Management

Project Statuses

• Endpoint: [GET] /v1/api/projects/statuses

• Description: Get a list of project statuses.

• Project Status Key:

  • ‘0':’Pipeline'.

  • ‘1':’SOW Created'.

  • ‘2':’Scheduled'.

  • ‘3':’In Progress'.

  • ‘4':’Delivered'.

Project Service Types

• Endpoint: [GET] /v1/api/projects/service-types

• Description: Get a list of project service types.

• Service Types Key:

  • ‘1':’Penetration Testing'.

  • ‘2':’Managed Vulnerability Scanning'.

  • ‘3':’Ransomware'.

  • ‘4':’Red Team Assessment'.

Issue Severities and Statuses

The following key should be used to determine the Issue Severity or Status.

• Issue Status Key:

  • '0': 'Draft',

  • '1': 'Published',

  • '2': 'Remediated - Verified',

  • '3': 'False Positive',

  • '4': 'Accept Risk',

  • '5': 'Suppressed',

  • '6': 'Remediated - Unverified',

  • '9': 'In Progress'

• Issue Severity Key:

  • '0': 'Info',

  • '1': 'Low',

  • '2': 'Medium',

  • '3': 'High',

  • '4': 'Critical'

Project Test Types

• Endpoint: [GET] /v1/api/test-types

• Description: Get a list of project test types