Vulnerabilities API

Overview

The Vulnerabilities API provides endpoints for managing vulnerability templates (default vulnerabilities), individual vulnerabilities, categories, and tracking information. This includes creating and updating vulnerability templates, searching vulnerabilities, managing remediation status, and organizing vulnerabilities by category. All endpoints require authentication via the FACTION-API-KEY header.

Get All Default Vulnerabilities (JSON)

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/default" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves all default vulnerability templates stored in the system in JSON format with custom fields support.

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns an array of DefaultVulnerabilityDTO objects.

long

Template ID

name

string

Vulnerability name

categoryId

long

Category ID

categoryName

string

Category name

description

string

Vulnerability description (HTML/Markdown)

recommendation

string

Remediation recommendation (HTML/Markdown)

severityId

integer

Severity level (0-9)

impactId

integer

Impact score (0-9)

likelihoodId

integer

Likelihood score (0-9)

active

boolean

Whether template is active

cvss31Score

string

CVSS 3.1 score

cvss31String

string

CVSS 3.1 vector string

cvss40Score

string

CVSS 4.0 score

cvss40String

string

CVSS 4.0 vector string

customFields

array

Array of custom field objects

Status Codes

200 - Success: All default vulnerabilities returned
401 - Not authorized
400 - Unknown error

Get All Default Vulnerabilities (CSV)

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/csv/default" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Accept: text/csv"

Retrieves all default vulnerability templates in CSV format.

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns CSV data with the following columns:

Id
Name
CategoryId
CategoryName
Description
Recommendation
SeverityId
ImpactId
LikelihoodId
isActive
CVSS31Score
CVSS31String
CVSS40Score
CVSS40String
CustomFields (JSON)

Status Codes

200 - Success: CSV data returned
401 - Not authorized
400 - Unknown error

Upload Default Vulnerabilities (CSV)

curl -X POST "https://your-faction-instance.com/api/vulnerabilities/csv/default" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: text/plain" \
  --data-binary @vulnerabilities.csv

Uploads default vulnerability templates to Faction in CSV format.

Authentication

FACTION-API-KEY

string

required

API authentication key

Request Body

CSV file with the following format:

id,vulnName,categoryId,categoryName,description,recommendation,severityId,impactId,likelihoodId,active,cvss31Score,cvss31String,cvss40Score,cvss40String
,SQL Injection,,Injection,SQL injection vulnerability description,Parameterized queries recommended,7,8,6,true,7.5,CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H,,

CSV Format Notes

id: If empty, creates a new vulnerability. If populated, updates existing vulnerability.
categoryId/categoryName: If categoryId is missing, categoryName is required. If category doesn’t exist, a new one is created.
categoryId: If populated, categoryName is ignored.

Status Codes

200 - Success: Vulnerabilities uploaded
401 - Not authorized
400 - Invalid CSV format or data

Upload Default Vulnerabilities (JSON)

curl -X POST "https://your-faction-instance.com/api/vulnerabilities/default" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "name": "SQL Injection",
      "categoryName": "Injection",
      "description": "SQL injection allows attackers to interfere with database queries",
      "recommendation": "Use parameterized queries and input validation",
      "severityId": 7,
      "impactId": 8,
      "likelihoodId": 6,
      "active": true,
      "cvss31Score": "7.5",
      "cvss31String": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
      "customFields": [
        {"key": "OWASP_Category", "value": "A03:2021"},
        {"key": "CWE_ID", "value": "CWE-89"}
      ]
    }
  ]'

Uploads default vulnerability templates in JSON format with custom fields support.

Authentication

FACTION-API-KEY

string

required

API authentication key

Request Body

Array of DefaultVulnerabilityDTO objects:

long

Template ID (if updating existing template)

name

string

required

Vulnerability name

categoryId

long

Category ID (required if categoryName not provided)

categoryName

string

Category name (required if categoryId not provided)

description

string

Description (supports Markdown, will be converted to HTML)

recommendation

string

Remediation recommendation (supports Markdown)

severityId

integer

Severity level (0-9)

impactId

integer

Impact score (0-9)

likelihoodId

integer

Likelihood score (0-9)

active

boolean

Whether template is active

cvss31Score

string

CVSS 3.1 score

cvss31String

string

CVSS 3.1 vector string

cvss40Score

string

CVSS 4.0 score

cvss40String

string

CVSS 4.0 vector string

customFields

array

Array of custom field objects with key and value properties

Response

vids

array

Array of created/updated vulnerability template IDs

Status Codes

200 - Success: Templates created/updated
400 - Invalid data (missing required fields, invalid category)
401 - Not authorized

Search Default Vulnerabilities

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/default/SQL" \
  -H "FACTION-API-KEY: your-api-key"

Searches for default vulnerability templates by name using partial matching (case-insensitive).

Path Parameters

name

string

required

Vulnerability name to search (partial matching supported)

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns an array of matching DefaultVulnerabilityDTO objects with custom fields.

Status Codes

200 - Success: Matching templates returned
401 - Not authorized
400 - Unknown error

Get Default Vulnerability by ID

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/default/getvuln/45" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves a specific default vulnerability template by ID.

Path Parameters

long

required

Default vulnerability template ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns a DefaultVulnerabilityDTO object with custom fields.

Status Codes

200 - Success: Template returned
400 - Invalid vulnerability template ID
401 - Not authorized

Get Vulnerability by ID

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/getvuln/789" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves a specific vulnerability instance by ID (not a template).

Path Parameters

long

required

Vulnerability ID

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Remediation or Manager role)

Response

Returns a VulnerabilityDTO object with custom fields.

Status Codes

200 - Success: Vulnerability returned
400 - No matching vulnerability found
401 - Not authorized

Get Vulnerability by Tracking ID

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/gettracking/JIRA-1234" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves a vulnerability by its assigned tracking ID (e.g., JIRA ticket number).

Path Parameters

track

string

required

Vulnerability tracking ID

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Remediation or Manager role)

Response

Returns a VulnerabilityDTO object with custom fields.

Status Codes

200 - Success: Vulnerability returned
400 - No matching tracking ID found
401 - Not authorized

Set Tracking ID

curl -X POST "https://your-faction-instance.com/api/vulnerabilities/settracking" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "vulnId=789" \
  -d "trackingId=JIRA-1234"

Assigns a tracking number to a vulnerability for integration with external ticketing systems.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Remediation or Manager role)

Form Parameters

vulnId

long

required

Vulnerability ID

trackingId

string

required

Tracking ID (e.g., JIRA ticket number)

Status Codes

200 - Success: Tracking ID assigned
400 - Vulnerability not found
401 - Not authorized

Set Vulnerability Status

curl -X POST "https://your-faction-instance.com/api/vulnerabilities/setstatus" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "vulnId=789" \
  -d "trackingId=JIRA-1234" \
  -d "isClosedDev=true" \
  -d "isClosedProd=false" \
  -d "devClosedDate=2024-03-15" \
  -d "prodClosedDate="

Sets the remediation status (open/closed) of a vulnerability in development or production environments.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Remediation or Manager role)

Form Parameters

vulnId

long

Vulnerability ID (required if trackingId not provided)

trackingId

string

Tracking ID (required if vulnId not provided)

isClosedDev

boolean

Set to true if fixed in development environment

isClosedProd

boolean

Set to true if fixed in production environment

devClosedDate

date

Date of remediation in development

prodClosedDate

date

Date of remediation in production

Status Codes

200 - Success: Status updated
400 - Vulnerability not found or invalid parameters
401 - Not authorized

Get All Vulnerabilities by Date Range

curl -X POST "https://your-faction-instance.com/api/vulnerabilities/all" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "start=01/01/2024" \
  -d "end=03/31/2024"

Retrieves all vulnerabilities discovered within a specified timeframe.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Assessor, Manager, or Remediation role)

Form Parameters

start

string

required

Start date of search (MM/DD/YYYY format)

end

string

End date of search (MM/DD/YYYY format). If not provided, returns all from start date to present.

Response

Returns an array of VulnerabilityDTO objects with custom fields.

Status Codes

200 - Success: Vulnerabilities returned
400 - Invalid date format
401 - Not authorized

Get All Categories

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/categories" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves all vulnerability categories ordered by name.

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns an array of CategoryDTO objects.

long

Category ID

name

string

Category name

Status Codes

200 - Success: Categories returned
401 - Not authorized

Get Category by ID

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/category/12" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves a specific vulnerability category by ID.

Path Parameters

long

required

Category ID

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns a CategoryDTO object.

Status Codes

200 - Success: Category returned
404 - Category not found
401 - Not authorized

Create Category

curl -X POST "https://your-faction-instance.com/api/vulnerabilities/category" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mobile Security"}'

Creates a new vulnerability category.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Manager role)

Request Body

name

string

required

Category name

Response

Returns the created CategoryDTO object.

Status Codes

200 - Success: Category created
400 - Invalid name or category already exists
401 - Not authorized (Manager permission required)

Get Risk Levels

curl -X GET "https://your-faction-instance.com/api/vulnerabilities/getrisklevels" \
  -H "FACTION-API-KEY: your-api-key"

Retrieves customized risk ranking levels configured in the system.

Authentication

FACTION-API-KEY

string

required

API authentication key

Response

Returns an array of risk level objects:

integer

Risk level ID

name

string

Risk level name (e.g., “Critical”, “High”, “Medium”, “Low”)

Status Codes

200 - Success: Risk levels returned
401 - Not authorized

Authorization Requirements

Default Vulnerabilities (Templates)

View/Search: Any authenticated user
Upload/Modify: Any authenticated user

Vulnerabilities (Instances)

View by ID/Tracking: Remediation or Manager role
Set Tracking/Status: Remediation or Manager role
Get All by Date: Assessor, Manager, or Remediation role

Notes

Markdown Support: Description and recommendation fields support Markdown syntax, which is automatically converted to HTML.
Custom Fields: Both default vulnerabilities (templates) and vulnerability instances support custom fields.
CVSS Versions: The system supports both CVSS 3.1 and CVSS 4.0 scoring.
Tracking Integration: Use tracking IDs to integrate with external ticketing systems like JIRA.
Remediation Tracking: Track remediation status separately for development and production environments.

Overview

Endpoints

​Overview

​Get All Default Vulnerabilities (JSON)

​Authentication

​Response

​Status Codes

​Get All Default Vulnerabilities (CSV)

​Authentication

​Response

​Status Codes

​Upload Default Vulnerabilities (CSV)

​Authentication

​Request Body

​CSV Format Notes

​Status Codes

​Upload Default Vulnerabilities (JSON)

​Authentication

​Request Body

​Response

​Status Codes

​Search Default Vulnerabilities

​Path Parameters

​Authentication

​Response

​Status Codes

​Get Default Vulnerability by ID

​Path Parameters

​Authentication

​Response

​Status Codes

​Get Vulnerability by ID

​Path Parameters

​Authentication

​Response

​Status Codes

​Get Vulnerability by Tracking ID

​Path Parameters

​Authentication

​Response

​Status Codes

​Set Tracking ID

​Authentication

​Form Parameters

​Status Codes

​Set Vulnerability Status

​Authentication

​Form Parameters

​Status Codes

​Get All Vulnerabilities by Date Range

​Authentication

​Form Parameters

​Response

​Status Codes

​Get All Categories

​Authentication

​Response

​Status Codes

​Get Category by ID

​Path Parameters

​Authentication

​Response

​Status Codes

​Create Category

​Authentication

​Request Body

​Response

​Status Codes

​Get Risk Levels

​Authentication

​Response

​Status Codes

​Authorization Requirements

​Default Vulnerabilities (Templates)

​Vulnerabilities (Instances)

​Categories

​Notes

Build docs developers (and LLMs) love

Overview

Get All Default Vulnerabilities (JSON)

Authentication

Response

Status Codes

Get All Default Vulnerabilities (CSV)

Authentication

Response

Status Codes

Upload Default Vulnerabilities (CSV)

Authentication

Request Body

CSV Format Notes

Status Codes

Upload Default Vulnerabilities (JSON)

Authentication

Request Body

Response

Status Codes

Search Default Vulnerabilities

Path Parameters

Authentication

Response

Status Codes

Get Default Vulnerability by ID

Path Parameters

Authentication

Response

Status Codes

Get Vulnerability by ID

Path Parameters

Authentication

Response

Status Codes

Get Vulnerability by Tracking ID

Path Parameters

Authentication

Response

Status Codes

Set Tracking ID

Authentication

Form Parameters

Status Codes

Set Vulnerability Status

Authentication

Form Parameters

Status Codes

Get All Vulnerabilities by Date Range

Authentication

Form Parameters

Response

Status Codes

Get All Categories

Authentication

Response

Status Codes

Get Category by ID

Path Parameters

Authentication

Response

Status Codes

Create Category

Authentication

Request Body

Response

Status Codes

Get Risk Levels

Authentication

Response

Status Codes

Authorization Requirements

Default Vulnerabilities (Templates)

Vulnerabilities (Instances)

Categories

Notes