SCAIFE Statistics Module API Definition
This API definition facilitates auditing static analysis alerts using classifiers, optional adaptive heuristics (active learning), and alert prioritization. The API enables jump-starting labeled datasets using test suites. It is intended to enable a wide range of users (with widely varying datasets, static analysis tools, machine learning expertise, and amount of labeled data) to benefit from using classifiers and sophisticated prioritization to automatically triage static analysis alerts.
Version: 1.2.1
BasePath:
SCAIFE API Copyright 2007-2020 Carnegie Mellon University. All Rights Reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Products derived from this software may not include 'Carnegie Mellon University,' 'SEI' and/or 'Software Engineering Institute' in the name of such derived product, nor shall 'Carnegie Mellon University,' 'SEI' and/or 'Software Engineering Institute' be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact permission@sei.cmu.edu. ACKNOWLEDGMENTS AND DISCLAIMERS: This material is based upon work funded and supported by the Department of Defense under Contract No. FA8702-15-D-0002 with Carnegie Mellon University for the operation of the Software Engineering Institute, a federally funded research and development center. The view, opinions, and/or findings contained in this material are those of the author(s) and should not be construed as an official Government position, policy, or decision, unless designated by other documentation. NO WARRANTY. THIS CARNEGIE MELLON UNIVERSITY AND SOFTWARE ENGINEERING INSTITUTE MATERIAL IS FURNISHED ON AN 'AS-IS' BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL. CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT INFRINGEMENT. [DISTRIBUTION STATEMENT A] This material has been approved for public release and unlimited distribution. Please see Copyright notice for non-US Government use and distribution. This material includes field names used in the Software Assurance Marketplace (SWAMP), a service that provides continuous software assurance capabilities to developers and researchers at https://www.mir-swamp.org/#. Copyright © 2012-2020 The Morgridge Institute for Research, Inc. All rights reserved. This material includes field names used in the Software Assurance Tool (SwAT), a tool that is used by analysts to analyze static analysis alerts from multiple static analysis tools. https://www.cerdec.army.mil/ Combat Capabilities Development Command (CCDC) C5ISR Center. All rights reserved. DM19-0572
http://apache.org/licenses/LICENSE-2.0.html
Access
[ Jump to Models ]
Table of Contents
Up
put /projects/{project_id}/packages/{package_id}/alerts
Forward new Alerts that have been uploaded to the DataHub and have a current open adaptive heuristic request for its respective package. Returns status message for the DataHub to track if the request was completed. (sendAlertUpdatesForClassifier)
Path parameters
project_id (required)
Path Parameter — The id of the project associated with these alerts
package_id (required)
Path Parameter — The id of the package associated with these alerts
Consumes
This API call consumes the following media types via the request header:
Request body
Body Parameter — Updated alert data
Request headers
Return type
Example data
Content-Type: application/json
{
"project_id" : "project_id",
"package_id" : "package_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
alert_updates_response
400
Unable to Upload Alerts
401
Invalid Token Request
403
Missing Required Tokens
404
Required Resources Not Found
default
Unexpected Error
error
Up
put /packages/tools/{tool_id}
Send FFSA or code metrics tool info to the Stats Module. When a new tool is uploaded, the DataHub can send new tool info for packages with open adaptive heuristic requests automatically to keep the Stats Module in sync. (sendNewTool)
Path parameters
tool_id (required)
Path Parameter — The id of the tool uploaded to the DataHub
Consumes
This API call consumes the following media types via the request header:
Request body
Body Parameter — Tool info, including name, version, plus FFSA checker info OR code metrics field info and package ids associated with this new tool.
Request headers
Return type
Example data
Content-Type: application/json
{
"message" : "message",
"request_id" : "request_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
request_token
400
Invalid Request
401
Invalid Token Request
403
Missing Required Tokens
404
Package Not Found
default
Unexpected Error
error
Provides Server Status (getStatus)
Request headers
Return type
Example data
Content-Type: application/json
{
"message" : "message",
"request_id" : "request_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
Server Is Running
request_token
400
Database Connection Lost
default
Unexpected Error
error
Up
put /classifiers/{classifier_instance_id}/adaptive_heuristics/close
Stop adaptive heuristic forward request. Send a request to close (set to false) the adaptive heuristic for the packages listed in the classifier instance. (closeAdaptiveHeuristicDataForwarding)
Path parameters
classifier_instance_id (required)
Path Parameter — The id of the classifier instance to run on the target domain
Consumes
This API call consumes the following media types via the request header:
Request headers
Return type
Example data
Content-Type: application/json
{
"message" : "message",
"classifier_instance_id" : "classifier_instance_id"
}
Responses
200
OK
close_adaptive_heuristics_response
400
Invalid Close Request
401
Invalid Token Request
403
Missing Required Tokens
404
Classifier Instance Unavailable
default
Unexpected Error
error
Create a new classifier instance. Send Classifier information including Automated Hyper-Parameter Optimization (AHPO) and Adaptive Heuristics to the Stats Module along with package_ids for packages to use in creating/training a classifier. Returns an id that is used to then run the classifier and any additional information for the classifier. (createClassifierInstance)
Consumes
This API call consumes the following media types via the request header:
Request body
Body Parameter — Classifier information to create
Request headers
Return type
Example data
Content-Type: application/json
{
"analysis_messages" : "{}",
"project_id" : "project_id",
"classifier_instance_id" : "classifier_instance_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
create_classifier_response
400
Unable to Create Classifier
401
Invalid Token Request
403
Missing Required Tokens
404
Required Resources Not Found
422
Data Lacks Verdicts Labeled 'True' and 'False'
501
Error Retrieving DataHub Information
default
Unexpected Error
error
Up
delete /classifiers/{classifier_instance_id}
Delete a specific classifier from the Stats module by classifier_instance_id. (deleteClassifierInstance)
Path parameters
classifier_instance_id (required)
Path Parameter — The id of the classifier to delete
Consumes
This API call consumes the following media types via the request header:
Request headers
Return type
Example data
Content-Type: application/json
{
"message" : "message",
"request_id" : "request_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
Classifier Successfully Deleted
request_token
400
Invalid Request
401
Invalid Token Request
403
Missing Required Tokens
404
Unable to Delete Classifier
default
Unexpected Error
error
Up
put /classifiers/{classifier_instance_id}
Edit a specific classifier from the Stats module by classifier_instance_id. (editClassifierInstance)
Path parameters
classifier_instance_id (required)
Path Parameter — The id of the classifier instance to edit
Consumes
This API call consumes the following media types via the request header:
Request body
Body Parameter — Classifier information to edit
Request headers
Return type
Example data
Content-Type: application/json
{
"analysis_messages" : "{}",
"project_id" : "project_id",
"classifier_instance_id" : "classifier_instance_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
create_classifier_response
400
Unable to Edit Classifier
401
Invalid Token Request
403
Missing Required Tokens
404
Required Resources Not Found
422
Data Lacks Verdicts Labeled 'True' and 'False'
501
Error Retrieving DataHub Information
default
Unexpected Error
error
Up
get /classifiers/{classifier_instance_id}
Get analysis for a specific Classifier including performance metrics. (getClassifierInstanceAnalysis)
Path parameters
classifier_instance_id (required)
Path Parameter — The id of the classifier to get analysis info
Consumes
This API call consumes the following media types via the request header:
Request headers
Return type
Example data
Content-Type: application/json
{
"probability_data" : [ {
"probability" : 0.8008281904610115,
"meta_alert_id" : "meta_alert_id"
}, {
"probability" : 0.8008281904610115,
"meta_alert_id" : "meta_alert_id"
} ],
"performance_metrics" : "{}",
"classifier_analysis" : "{}",
"classifier_instance_id" : "classifier_instance_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
application/jsontext/html
Responses
200
OK
analysis_results
400
Invalid Request
401
Invalid Token Request
403
Missing Required Tokens
404
Classifier Information Unavailable
default
Unexpected Error
error
List all classifiers and their associated data. Use the ids returned from this request to work with classifiers. (listClassifiers)
Consumes
This API call consumes the following media types via the request header:
Request headers
Return type
Example data
Content-Type: application/json
[ {
"classifier_id" : "classifier_id",
"classifier_type" : "classifier_type",
"adaptive_heuristics" : [ {
"adaptive_heuristic_name" : "adaptive_heuristic_name",
"adaptive_heuristic_id" : "adaptive_heuristic_id",
"adaptive_heuristic_parameters" : "{}"
}, {
"adaptive_heuristic_name" : "adaptive_heuristic_name",
"adaptive_heuristic_id" : "adaptive_heuristic_id",
"adaptive_heuristic_parameters" : "{}"
} ],
"ahpos" : [ {
"ahpo_id" : "ahpo_id",
"ahpo_name" : "ahpo_name",
"ahpo_parameters" : "{}"
}, {
"ahpo_id" : "ahpo_id",
"ahpo_name" : "ahpo_name",
"ahpo_parameters" : "{}"
} ]
}, {
"classifier_id" : "classifier_id",
"classifier_type" : "classifier_type",
"adaptive_heuristics" : [ {
"adaptive_heuristic_name" : "adaptive_heuristic_name",
"adaptive_heuristic_id" : "adaptive_heuristic_id",
"adaptive_heuristic_parameters" : "{}"
}, {
"adaptive_heuristic_name" : "adaptive_heuristic_name",
"adaptive_heuristic_id" : "adaptive_heuristic_id",
"adaptive_heuristic_parameters" : "{}"
} ],
"ahpos" : [ {
"ahpo_id" : "ahpo_id",
"ahpo_name" : "ahpo_name",
"ahpo_parameters" : "{}"
}, {
"ahpo_id" : "ahpo_id",
"ahpo_name" : "ahpo_name",
"ahpo_parameters" : "{}"
} ]
} ]
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
400
Invalid Request
401
Invalid Token Request
403
Missing Required Tokens
default
Unexpected Error
error
Up
put /classifiers/{classifier_instance_id}/retrain
Returns new probability values if there are updates from the selected classifier_instance. (retrain)
Path parameters
classifier_instance_id (required)
Path Parameter — The id of the classifier instance to run on the target domain
Consumes
This API call consumes the following media types via the request header:
Request body
Body Parameter — Information to send close adaptive heuristic request
Request headers
Return type
Example data
Content-Type: application/json
{
"probability_data" : [ {
"probability" : 0.8008281904610115,
"meta_alert_id" : "meta_alert_id"
}, {
"probability" : 0.8008281904610115,
"meta_alert_id" : "meta_alert_id"
} ],
"project_id" : "project_id",
"classifier_analysis" : "{}",
"classifier_instance_id" : "classifier_instance_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
classifier_results
204
Not Updates
400
Unable to Run Classifier
401
Invalid Token Request
403
Missing Required Tokens
404
Required Resources Not Found
422
Data Lacks Verdicts Labeled 'True' and 'False'
501
Error Retrieving DataHub Information
default
Unexpected Error
error
Up
put /classifiers/{classifier_instance_id}/projects/{project_id}
Run a specific classifier instance on the project identified by id in the path. The response contains estimated class probablities and analysis of classifier performance. (runClassifierInstance)
Path parameters
classifier_instance_id (required)
Path Parameter — The id of the classifier instance to run on the target domain
project_id (required)
Path Parameter — The id of the project containing the packages
Consumes
This API call consumes the following media types via the request header:
Request headers
Return type
Example data
Content-Type: application/json
{
"probability_data" : [ {
"probability" : 0.8008281904610115,
"meta_alert_id" : "meta_alert_id"
}, {
"probability" : 0.8008281904610115,
"meta_alert_id" : "meta_alert_id"
} ],
"project_id" : "project_id",
"classifier_analysis" : "{}",
"classifier_instance_id" : "classifier_instance_id"
}
Produces
This API call produces the following media types according to the request header;
the media type will be conveyed by the response header.
Responses
200
OK
classifier_results
400
Unable to Run Classifier
401
Invalid Token Request
403
Missing Required Tokens
404
Required Resources Not Found
501
Error Retrieving DataHub Information
default
Unexpected Error
error
[ Jump to Methods ]
Table of Contents
alert - alert_updates_response - analysis_results - checker_mappings - classifier_instance - classifier_instance_data - classifier_results - classifier_results_probability_data - close_adaptive_heuristics_response - condition - create_classifier_response - determination - determination_dangerous_construct_list - determination_dead_list - determination_flag_list - determination_ignored_list - determination_inapplicable_environment_list - determination_notes_list - determination_verdict_list - error - list_classifiers_response - list_classifiers_response_adaptive_heuristics - list_classifiers_response_ahpos - message - meta_alert - metrics - multiple_alerts - packages_with_tool_data - packages_with_tool_data_tool_data - request_token - source_mappings - sourcefile - sourcefunction - taxonomy - secondary_message -
alert_id
tool_id
checker_id
primary_message
secondary_messages (optional)
project_id (optional)
package_id (optional)
classifier_instance_id (optional)
probability_data (optional)
classifier_analysis (optional)
performance_metrics (optional)
checker_id (optional)
checker_name (optional)
tool_id (optional)
conditions (optional)
classifier_id
classifier_type (optional)
classifier_instance_name (optional)
project_ids
ahpo_id (optional)
ahpo_name (optional)
ahpo_parameters (optional)
adaptive_heuristic_id (optional)
adaptive_heuristic_name (optional)
adaptive_heuristic_parameters (optional)
project_id
String The id of the target project to run the classifier on
timestamp
Date The current time format: date-time
classifier_instance_id (optional)
project_id
String ID of project in the target domain
probability_data
classifier_analysis (optional)
meta_alert_id (optional)
probability (optional)
classifier_instance_id (optional)
message (optional)
condition_id (optional)
condition_name (optional)
title (optional)
platforms (optional)
code_language_ids (optional)
condition_fields (optional)
Object Fields associated with this condition, i.e., likelihood
taxonomy (optional)
classifier_instance_id (optional)
project_id (optional)
analysis_messages (optional)
Object Additional information that will help to understand this classifier instance's performance
flag_list (optional)
verdict_list (optional)
ignored_list (optional)
dead_list (optional)
inapplicable_environment_list (optional)
dangerous_construct_list (optional)
notes_list (optional)
dangerous_construct (optional)
String Options for this field include Unknown, No Risk, Low Risk, Medium Risk, and High Risk
timestamp (optional)
dead (optional)
String Options for this field include True, False, and Unknown
timestamp (optional)
flag (optional)
timestamp (optional)
ignored (optional)
String Options for this field include True, False, and Unknown
timestamp (optional)
inapplicable_environment (optional)
String Options for this field include True, False, and Unknown
timestamp (optional)
notes (optional)
timestamp (optional)
verdict (optional)
String 'Options for this field include Unknown, Complex, False, Dependent, and True
timestamp (optional)
classifier_id (optional)
classifier_type (optional)
ahpos (optional)
adaptive_heuristics (optional)
adaptive_heuristic_id (optional)
adaptive_heuristic_name (optional)
adaptive_heuristic_parameters (optional)
ahpo_id (optional)
ahpo_name (optional)
ahpo_parameters (optional)
line_start
line_end (optional)
filepath
source_file_id
source_function_id (optional)
meta_alert_id
condition_id (optional)
filepath (optional)
line_number (optional)
determination (optional)
alert_ids (optional)
auto_verdict (optional)
source_files (optional)
meta_alerts (optional)
alerts (optional)
package_ids (optional)
tool_data (optional)
tool_name (optional)
tool_version (optional)
tool_type (optional)
source_mappings (optional)
code_metrics_data (optional)
request_id
String Id used to correlate messages with each other
message (optional)
mapping_source (optional)
checker_mappings (optional)
source_file_id (optional)
filename (optional)
filepath (optional)
filepath_depth (optional)
defect_info (optional)
code_metrics_data (optional)
functions (optional)
source_function_id (optional)
name (optional)
line_start (optional)
line_end (optional)
code_metrics_data (optional)
taxonomy_id
taxonomy_name
String Name of the taxonomy, i.e., CERT or CWE
taxonomy_version
description (optional)
line_start
line_end (optional)
filepath
source_file_id
source_function_id (optional)
message_text