Importing Your Vulnerability Templates Via the API

You may have developed your own vulnerability templates over the years, or you may prefer editing them in another editor such as Obsidian or Sublime, rather than using the web interface. Regardless of your approach, Faction enables you to upload your templates in CSV and JSON formats via the API. Additionally, reports can be generated in markdown, HTML, or a combination of both.

The api docs can be found on your instance by navigating to https: //YourHost/api-docs:

Generating an API Key

You must have the API Key permission on your user to use the API. It it not set by default.

After enabling the setting, you can access your API Key by navigating to your profile, located in the upper right corner of the Faction interface. Simply clicking anywhere inside the API key box will reveal the key to you.

CSV File Structure

Id*	Name	Category Id*	Category Name*	Description	Recommendation	Severity Id	Impact Id	Likelihood Id	active

If the ID field is empty, a new vulnerability will be created. If the ID field is populated, it will overwrite the vulnerability with the same ID.

If the Category ID is missing, the categoryName field is required. If a category with the same name exists, the existing category will be used.

If the categoryName does not match an existing category, a new category will be created.

If the Category ID is populated, the Category Name field is ignored.

Example 1: Create a New Vulnerability Template in CSV

Example CSV

,"Cross Site Scripting",, Unvalidated Input, "XSS is Bad and stuff..\n```\nCode snippet\n```", "Fix it! here is a link [here](https://www.a.b.com)", 4, 4,4,true

The provided example will create a new template for cross-site scripting. Here are a few key points to note:

The first column (ID column) is left blank. Since there is no ID specified, a new template will be created.
The third column (Category ID) is also blank, so Faction will refer to the fourth column (Category Name). If Unvalidated Input is not already a category in Faction, it will be created.
The Description and Recommendation fields are written in markdown syntax. Ensure that these columns are enclosed in double quotes (") and that new lines are properly escaped (\n).
The severity IDs must correspond to the severity levels configured in Faction. You can find these numbers in Admin->Settings-> Risk Level Settings. The default severity levels are: Critical (5), High (4), Medium (3), Low (2), Recommended (1), Informational (0). Ensure that the severity IDs match these levels accordingly.

Submit through the API

curl -X 'POST' \ 
'http://localhost:8080/api/vulnerabilities/csv/default' \ 
-H 'accept: application/json' \ 
-H 'FACTION-API-KEY: 6be51daa-6f6f-42d3-8b04-b924a0045eff' \ 
-H 'Content-Type: text/plain' \ 
-d ',"Cross Site Scripting",, Unvalidated Input, "XSS is Bad and stuff..\n```\nCode snippet\n```", "Fix it! here is a link [here](https://www.a.b.com)", 4, 4,4,true'

Example 2: Updating a Vulnerability Template in CSV

First, you need to download the current list of vulnerabilities from the API.

Get a CSV List of Default Vulnerabilities

curl -X 'GET' \ 
'http://localhost:8080/api/vulnerabilities/csv/default' \ 
-H 'accept: text/csv' \ 
-H 'FACTION-API-KEY: 6be51daa-6f6f-42d3-8b04-b924a0045eff'

Example Response:

"2","Generic Vulnerability","2","Uncategorized","","","4","4","4","true" "18","Cross Site Scripting","4","Unvalidated Input","<p>XSS is Bad and stuff..</p> <pre><code>Code snippet </code></pre> <br />","<p>Fix it! here is a link <a href=""https://www.a.b.com"">here</a></p> <br />","4","4","4","true"

Now to Update a Template Let's update the Cross Site Scripting Template by changing the description to the following.

XSS is fun to exploit with this code snippet\n ```\nSnipity snip\n```

The API Request would look like this:

curl -X 'POST' \ 
'http://localhost:8080/api/vulnerabilities/csv/default' \ 
-H 'accept: application/json' \ 
-H 'FACTION-API-KEY: 6be51daa-6f6f-42d3-8b04-b924a0045eff' \ 
-H 'Content-Type: text/plain' \ 
-d '"18","Cross Site Scripting","4","Unvalidated Input","XSS is fun to exploit with this code snippet\n ```\nSnipity snip\n```","<p>Fix it! here is a link <a href=""https://www.a.b.com"">here</a></p> <br />","4","4","4","true"'

Now if we pull the list again the results look like this: Request

curl -X 'GET' \ 
'http://localhost:8080/api/vulnerabilities/csv/default' \ 
-H 'accept: text/csv' \ 
-H 'FACTION-API-KEY: 6be51daa-6f6f-42d3-8b04-b924a0045eff'

Response

"2","Generic Vulnerability","2","Uncategorized","","","4","4","4","true" "18","Cross Site Scripting","4","Unvalidated Input","<p>XSS is fun to exploit with this code snippet</p> <pre><code>Snipity snip </code></pre> <br />","<p>Fix it! here is a link <a href=""https://www.a.b.com"">here</a></p> <br /> <br />","4","4","4","true"

JSON File Structure

  [
      {
        "Id": 2,
        "Name": "Generic Vulnerability",
        "CategoryId": 2,
        "CategoryName": "Uncategorized",
        "Description": "",
        "Recommendation": "",
        "SeverityId": 4,
        "LikelihoodId": 4,
        "ImpactId": 4,
        "Active": true
      }
  ]

If the ID is missing, a new vulnerability will be created. If the ID is populated, it will overwrite the vulnerability with the same ID.

If the Category ID is missing, the categoryName is required. If a category with the same name exists, the existing category will be used.

If the categoryName does not match an existing category, a new category will be created.

If the Category ID is populated, the Category Name field is ignored.

Example 1: Create All New Vulnerability Template in JSON

Example JSON

[
    {
        "Name": "Cross Site Scripting",
        "CategoryName": "Unvalidated Input",
        "Description": "XSS is Bad and stuff..\n```\nCode snippet\n```",
        "Recommendation": "Fix it! here is a link [here](https://www.a.b.com)",
        "LikelihoodId": 4,
        "ImpactId": 4,
        "SeverityId": 4,
        "Active": true
    }
]

The provided example will create a new template for cross-site scripting. Here are a few key points to note:

The ID is missing. Since there isn't an ID to relate it, a new template will be created.
The CategoryId is missing, so Faction will need to look at the CategoryName. If Unvalidated Input is not already a category, then Faction will create it.
The Description and Recommendation fields are written in markdown syntax.
Ensure that the severity IDs match the severity levels you have set in Faction. You can find these numbers in Admin->Settings-> Risk Level Settings. The defaults are Critical (5), High (4), Medium (3), Low (2), Recommended (1), Informational (0).

The API Request looks like this to add this vulnerability template:

curl -X 'POST' \ 
'http://localhost:8080/api/vulnerabilities/default' \ 
-H 'accept: application/json' \ 
-H 'FACTION-API-KEY: a0d2fff7-7462-458c-ba7b-d93d99b7280a' \ 
-H 'Content-Type: application/json' \ 
-d '[ 
    { 
        "Name": "Cross Site Scripting", 
        "CategoryName": "Unvalidated Input", 
        "Description": "XSS is Bad and stuff..\n```\nCode snippet\n```",
        "Recommendation": "Fix it! here is a link [here](https://www.a.b.com)",
        "LikelihoodId": 4, 
        "ImpactId": 4, 
        "SeverityId": 4, 
        "Active": true 
    } 
]'

Example 2: Updating a Vulnerability Template in JSON

First, you need to download the current list of vulnerabilities from the API.

Get a JSON List of Default Vulnerabilities

curl -X 'GET' \ 
'http://localhost:8080/api/vulnerabilities/default' \ 
-H 'accept: application/json' \ 
-H 'FACTION-API-KEY: a0d2fff7-7462-458c-ba7b-d93d99b7280a'

Response:

href="#__codelineno-12-1">[ { "CategoryId": 2, "ImpactId": 4, "Active": true, "Description": "", "CategoryName": "Uncategorized", "LikelihoodId": 4, "Id": 2, "Recommendation": "", "SeverityId": 4, "Name": "Generic Vulnerability" }, { "CategoryId": 4, "ImpactId": 4, "Active": true, "Description": "XSS is Bad and stuff..\n```\nCode snippet\n```", "CategoryName": "Unvalidated Input", "LikelihoodId": 4, "Id": 5, "Recommendation": "Fix it! here is a link [here](https://www.a.b.com)", "SeverityId": 4, "Name": "Cross Site Scripting" } ]

Now to Update a Template Let's update the Cross-Site Scripting Template by changing the description to the following.

XSS is fun to exploit with this code snippet\n ```\nSnipity snip\n```

The API Request would look like this:

curl -X 'POST' \
  'http://localhost:8080/api/vulnerabilities/default' \
  -H 'accept: application/json' \
  -H 'FACTION-API-KEY: a0d2fff7-7462-458c-ba7b-d93d99b7280a' \
  -H 'Content-Type: application/json' \
  -d '[ {
    "CategoryId": 4,
    "ImpactId": 4,
    "Active": true,
    "Description": "XSS is fun to exploit with this code snippet\n ```\nSnipity snip\n```",
    "CategoryName": "Unvalidated Input",
    "LikelihoodId": 4,
    "Id": 5,
    "Recommendation": "Fix it! here is a link [here](https://www.a.b.com)",
    "SeverityId": 4,
    "Name": "Cross Site Scripting"
  }]'

Now if we pull the list again the results look like this: Request

curl -X 'GET' \ 
'http://localhost:8080/api/vulnerabilities/default' \ 
-H 'accept: text/csv' \ 
-H 'FACTION-API-KEY: 6be51daa-6f6f-42d3-8b04-b924a0045eff'

Response

[
  {
    "CategoryId": 2,
    "ImpactId": 4,
    "Active": true,
    "Description": "",
    "CategoryName": "Uncategorized",
    "LikelihoodId": 4,
    "Id": 2,
    "Recommendation": "",
    "SeverityId": 4,
    "Name": "Generic Vulnerability"
  },
  {
    "CategoryId": 4,
    "ImpactId": 4,
    "Active": true,
    "Description": "<p>XSS is fun to exploit with this code snippet</p>\n<pre><code>Snipity snip\n</code></pre>\n<br />",
    "CategoryName": "Unvalidated Input",
    "LikelihoodId": 4,
    "Id": 5,
    "Recommendation": "<p>Fix it! here is a link <a href=\"https://www.a.b.com\">here</a></p>\n<br />",
    "SeverityId": 4,
    "Name": "Cross Site Scripting"
  }
]

Using Swagger

Instead of using CURL as show above you can use the API docs pages to submit directly to your API to test things out.

Just navigate to https: //YourHost/api-docs and select any of the API's available. You will need your API Key that can be found in your profile.

Below is an example of using swagger to update a Template with JSON.