Automating Serpico

There are two main ways to automate Serpico functionality, the API or through scripting. The API is meant to be used remotely, scripting locally.

Scripting

Example scripts are contained in the '/scripts' directory of Serpico. Any Serpico functionality can be done with scripting. Obviously be careful as you are modifying the live database.

The following is a simple example to print out all reports and findings from the database:

# An example script to print out the names of all reports and their findings.
# => Must be run from the Serpico root directory

require './model/master.rb'
require 'json'

# Grab all reports from the database
reports = Reports.all()

# Iterate each report
reports.each do |report|
	# Grab all of the findings from the reports
	findings = Findings.all(:report_id => report.id)

	# Print the results
	puts "Report Name: #{report.report_name}"
	findings.each do |finding|
		puts "---- #{finding.title}"
	end
end

To run this script you must be in the Serpico root directory:

~/Serpico> ruby scripts/list_reports.rb

More complicated examples:

Import VulnDB Into Serpico Template Database

API

For now the API is read only and offers access to reports and findings (see specification below for more info). In the future this maybe expanded. The following is a simple example to print out all reports and findings using the API:

# This script outputs a list of report names and findings for each report

# unirest is much less painful than ruby http
require 'unirest'

# Set your info here
creds = { :username => "administrator", :password => "[PASSWORD]" }
host = "127.0.0.1:8443"

# authenticate to API
response = Unirest.post "https://#{host}/v1/session",
                        headers:{ "Accept" => "application/json" },
                        parameters:creds
if response.body.size < 10
	puts "|-| Unknown API Authentication error, please verify credentials"
	exit
end

# Set the api key
api_key = response.body

# Get the report list via the API
reports = Unirest.post "https://127.0.0.1:8443/v1/reports",
                        headers:{ "Accept" => "application/json" },
                        parameters:{ :session => api_key}

puts ""
# Iterate the reports list
reports.body.each do |report|
	# Obtain the findings for that report id
	findings = Unirest.post "https://127.0.0.1:8443/v1/findings",
                        headers:{ "Accept" => "application/json" },
                        parameters:{ :session => api_key, :report_id => report["id"]}

	### Handle the data here, in this case we print the report name and the findings
    puts "Report Name:#{report["report_name"]}"
	findings.body.each do |find|
		puts "--- #{find['title']}"
	end
	puts ""
end

This script can be run from anywhere:

~/> ruby scripts/list_reports_api.rb

API Endpoints

/v1/session

• Input: username, password
• Output: session_id
• Failed Auth: Blank Response

/v1/reports

• Input: session
• Optional Input: report_id
• Output: reports

/v1/findings

• Input: session, report_id
• Output: findings