A library for creating and managing SARIF files.
Project description
simple-sarif
Table of Contents
- simple-sarif
Features
- Generate SARIF files with rules and results
- Filter out results from a SARIF
- Convert SARIF to a table or CSV
- Find results and rules from a SARIF
- Aggregate results from a SARIF into one result for every rule in a run
- Verify a SARIF complies with its schema
Installation
Simply run the following command to install it:
pip install simple-sarif
To create a simple-sarif object, run:
import simple_sarif
var = simple_sarif.Sarif()
Function Descriptions
NOTE: All arguments are required unless otherwise stated.
init
init runs when a sarif object is created using var = simple_sarif.Sarif()
.
init will create a new SARIF object stored in self.sarif. This is what's being modified when running the other commands.
A filename may also be provided. In this situation, it will read the file and store it as self.sarif.
init Arguments
- file="FILENAME" (optional)
- Default is
None
. - If left empty, a filename will need to be specified when running save.
- If the given filename is a file that exists, its contents, assumed to be a SARIF file, will be read and saved in self.sarif.
- Default is
- validate=[True/False] (optional)
- Default is
True
. - This tells the code whether it should validate that the given SARIF file matches its schema. If not, the object won't be created.
- Default is
- recreate=[True/False] (optional)
- Default is
False
. (It will add to the file.) - Determines if it will add to results and rules to a SARIF file or delete the file to start adding results from scratch.
- Default is
init Usage Example
var = simple_sarif.Sarif(file="sarif.json", validate=True, recreate=True)
add_rule
add_rule appends a new rule to the self.sarif variable. If the ruleID already exists, the rule will be overwritten.
add_rule Arguments
-
name
- Gives the rule a name (e.g. Secrets Found)
-
ruleId
- Gives the rule a ruleId. RuleIds usually look like
GGS001
orfound.secrets
.
- Gives the rule a ruleId. RuleIds usually look like
-
shortDescription
- Adds a concise description of what the rule is for.
-
fullDescription
- A longer description of the rule's purpose.
-
messageStrings
- A dictionary for messages to be referenced when a result is added. This is formatted as follows:
{ "note": { "text": "The rule passed." # this could be any string. }, "error": { "text": "The rule failed." } }
-
properties (optional)
- Added information in the form of a dictionary to provide context for the rule. Here's how it's used:
{ "key1": "Local" "key2": var1 }
add_rule Usage Example
Note: The properties tab has been left empty, but an example is given above.
var.add_rule("Test Rule", "test.rule",
"This is being used as an example.",
"For the purposes of demonstrating the usage of add_rule, this rule was made. It is only going to be used in documentation.",
{
"note": {
"text": "Rule passed."
},
"error": {
"text": "Rule failed."
}
})
add_result
Adds a result based on some provided ruleID. The ruleID must be one that matches a rule inside of the SARIF.
add_result Arguments
-
ruleId
- This functions the same as in add_rule. It must match a ruleID inside of the rules section of the SARIF file.
-
level
- Marks whether the result is a pass or fail, indicated by "note" or "error".
-
message_id
- The message string inside of the result meant to explain what happened. This is usually based on the messageStrings inside of the associated rule.
-
arguments (optional by leaving it as [])
- An array of arguments for dynamic content in a result's message (e.g. {0} in the message_id is the first value in the arguments array).
-
properties (optional)
- A dictionary of extra data to give context for the result, just like as in add_rule. See here for more information.
-
locations (optional)
- A list of information regarding the location, be it physicalLocation or logicalLocation, that the result is referencing. Here is an example using physicalLocation:
[{ "physicalLocation": { "artifactLocation": { "uri": "file///path" }, "region": { "startLine": 5, "startColumn": 6 } } }]
add_result Usage Example
var.add_result("test.rule", "note", "Successful run of '{0}'", ["test"], {
"run_type": "local"
}, [{
"physicalLocation": {
"artifactLocation": {
"uri": "file///path"
},
"region": {
"startLine": 5,
"startColumn": 6
}
}
}])
get_sarif
Returns entire self.sarif object to be stored and manipulated manually.
get_sarif Usage Example
sarif_data = var.get_sarif()
save
Saves self.sarif data to a file.
save Arguments
- validate=[True/False]
- Defaults to
False
. - Tells the script whether it should check that the SARIF matches its schema before saving it to a file.
- Defaults to
- filename="FILENAME" (optional if one was not given earlier)
- Defaults to
None
. - If a filename was not given when the
simple_sarif
object was created, one may be provided here.- This can also be used to save to a different file if a filename was given earlier.
- If no filename is given, the
save
method will fail.
- Defaults to
save Usage Example
var.save(validate=True, filename="sarif.json")
get_table_result
Returns given data as a dictionary.
get_table_result Arguments
ruleName, ruleId, level, shortDescription, message, ruleProperties, and resultProperties were all explained before. See add_result arguments and add_rule arguments.
to_table
Converts SARIF (Static Analysis Results Interchange Format) results to a table format.
This function processes SARIF results from a SARIF-formatted report stored in self.sarif
.
It extracts information about each result and its corresponding rule, and formats this
information into a table-like data structure (list of dictionaries).
This function returns a list of dictionaries, where each dictionary represents a row in the table.
to_table Arguments
- add_properties=[True/False]
- Defaults to
True
. - Determines if the function will check for the
properties
field, and if it's found, add it to the table.
- Defaults to
to_table Usage Example
table = var.to_table(add_properties=False)
to_csv
Converts the data generated by the to_table method to a CSV format and writes it to a file. The first row of the CSV is the header, and each following row represents one result.
to_csv Arguments
- filename
- A string containing the name of the CSV file being written to.
- add_properties=[True/False]
- Defaults to
True
. - Sets add_properties value for the to_table method.
- Defaults to
to_csv Usage Example
var.to_csv(filename="sarif.csv", add_properties=False)
rfilter_out
Filters out results from the self.sarif object based on provided ruleIDs and levels. If both ruleIDs and levels have a value, it will ONLY filter out rules that match both.
rfilter_out Arguments
NOTE: ruleIDs and levels are both optional, but at least one must be given or the method will produce an error.
- ruleIDs (optional)
- A list of every ruleID to check for when filtering results.
- levels (optional)
- A list of every level to check for when filtering results.
- filename (optional)
- Just as with the
save
function, a filename is required if one was not set during initialization.
- Just as with the
rfilter_out Usage Example
var.rfilter_out(ruleIDs=["test.rule", "test.rules"], levels=["note"], filename=None)
rfilter_only
Filters the results of the self.sarif object to only include results that match the given ruleIDs and levels. Like rfilter_out, setting ruleIDs and levels will cause any result not matching both to be deleted.
rfilter_only Arguments
See here.
rfilter_only Usage Example
var.rfilter_only(ruleIDs=["test.rule"], levels=["note", "error"], filename="sarif.json")
find_results
Returns a list of results from the self.sarif or a file matching given ruleIDs and levels. Again, like rfilter_out, declaring both ruleIDs and levels will only return results that match both.
find_results Arguments
See here.
find_results Usage Example
results = var.find_results(ruleIDs=["test.rule"], levels=["error"])
find_rule
Returns a list of rules matching given ruleIDs.
find_rule Arguments
- ruleIDs
- A list of ruleIDs to search for.
- filename (optional)
- See here.
find_rule Usage Example
rules = var.find_rule(ruleIDs=["test.rules", "test.rule"], filename="sarif.json")
aggregate_results
Gathers results from every run in a SARIF file or the self.sarif object and turns them into one result per rule per run. The end level for this result can be configured to fail if one result is a fail or only if all of them fail.
aggregate_results Arguments
- fail_type=["one"/"all"]
- Defaults to
"one"
. - A fail_type of
"one"
means that the final result for the rule will beerror
if one of the results was anerror
. - A fail_type of
"all"
will cause the end result to beerror
only if every result was anerror
.
- Defaults to
- remove_aggregated=[True/False]
- Defaults to
True
. - Tells the function if it should delete the results it aggregates.
- Defaults to
- filename (optional)
- See here.
aggregate_results Usage Example
var.aggregate_results(fail_type="all", remove_aggregated=False, filename=None)
verify_sarif
Checks the self.sarif object or a SARIF file to see if it matches its schema if one is provided in the file.
It accomplishes this by downloading the URI in the $schema
field.
If no schema is found or the link is invalid, the method will not raise an error, instead warning the user and returning True
.
If the SARIF fails validation, the script will return False
, indicating an error.
verify_sarif Arguments
- filename (optional)
- See here.
verify_sarif Usage Example
validation_result = var.verify_sarif(filename="sarif.json")
if not validation_result:
print("SARIF validation failed.")
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for simple_sarif-1.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 27430a0f42dae0419d2375d8960e907aa7688221e582ee1f46396da6565ef343 |
|
MD5 | c4ab87a9cf4ceb75fa2685610ee3445a |
|
BLAKE2b-256 | 15e7eb38195da35f25f497ee26fc39b8eee1d4ec79f8ac738e60db2fd38fe88a |