Faction includes two different API’s. One is REST based and will allow you to query and create just about anything that you can do via the web interface. You can write your one scripts to update findings, create assessments, or run reports.
The Second API is our Integration API and it is event triggered. This allows you to run custom code to integrate Faction into your existing systems like Jira or your own application inventory program. This post will discuss how you could integrate Faction into Jira to submit bugs directly to development teams for tracking.
INTEGRATION API WEB INTERFACE
Log into Faction as an administration and navigate to the Integration API page. It should look something like the following screenshot. On this page you can write custom python code that will execute when certain conditions happen inside of Faction. There are two boxes on the right of the screen. These inform you of the input arguments and output variables that are available to you. These are accessible from the ‘inputs’ variable and have a class type of VTKVPair. This is a simple key-value pair object that you can use. All outputs are expected to be Arrays of VTKVPairs. This might sound cumbersome at first but its really easy. Just keep reading.
ACCESSING INPUT VARIABLES:
Input variables are accessible as key-value pairs with the ‘key’ existing from the list of ‘Input Variables’ in the top right box of the page. For referrence here is the full set of variables that can be accessed on an Assessment Completed Event.
start assessor engagement end completed remediation appid distro appname vulns[ vulnId, vulnName, severity, desc ]
To access the completed time of the assessment then you could write python code as follows.
compDate = inputs.get('completed')
Vulnerability data has a similar format but is an array of vulnerabilities for this assessment. You could access it as follows:
vs = inputs.get('vulns')
for v in vs:
name=v.get('vulnName')
desc=v.get('desc')
RETURNING VARIABLES TO FACTION
You can update the Faction database with external sources. These variables that are accepted back into Faction are defined in the Output Format Table. Below are the output variables for an Assessment Completed Event.
vulnId tracking
These variables must be Key-Value pairs in an Array. To return an updated trackingId that would be from an external system you do something similar to the following code:
array=VTArray()
vs = inputs.get('vulns')
for v in vs:
track=VTKVPair()
trackingID=YourFunction2GetData(v.get('vulnName'), v.get('desc'))
track.put('vulnId', v.get('vulnId')) #keep our current vulnerability id
track.put('tracking', trackingID) # update the Faction Vulnerability Tracking Id
array.add(track) # add the keyvalue pairs to the output array
return array
PUT IT ALL TOGETHER
Lets tie faction into Jira so that when an assessment is complete we can submit all our vulnerabilities into Jira and update Faction with the Jira Ids. Below is our code:
from vtrack.pylib import VTKVPair
from vtrack.pylib import VTArray
from vtrack.pylib import VTIntegration
import sys
#we need to import external libraries
sys.path.append("C:\\Python27\\lib\\site-packages")
sys.path.append("C:\\tmp")
import requests
import json
import html2jira
import customPass; #this is a custom file that sets out Jira Password.
class API(VTIntegration):
def runit(self, inputs):
array=VTArray()
vs = inputs.get('vulns')
for v in vs:
h = html2jira.HTML2Jira() #import this file that converts HTML to Jira formating.
h.ignore_links = True
h.ignore_images = True
track=VTKVPair()
headers = {'Authorization': 'Basic ' + customPass.password,
'Content-Type': 'application/json'}
r = requests.post("https://yourjira.atlassian.net/rest/api/2/issue/", data=json.dumps({
"fields": {
"project":
{
"key": "TI"
},
"summary": v.get('vulnName'),
"description": h.handle(v.get('desc')),
"issuetype": {
"name": "Bug"
}
}
}), headers=headers)
j = r.json()
track.put('vulnId', v.get('vulnId'))
track.put('tracking', 'JIRA-' + j.get('id'))
array.add(track)
print array
return array
After finalizing an assessment our vulnerabilities are uploaded to Jira and formatted similar to how they exist in the report. Notice full vulnerability exploit steps and descriptions are added to the issues created in JIRA.
Now we can query for the vulnerability in Faction and find the Jira ID.
Search by our Tracking Id in JIRA:
Reports are automatically updated the the external system’s tracking number as well.
