Package: simple-sarif
simple-sarifTable of Contentssimple-sarifTable of ContentsFeaturesInstallationFunction Descriptionsinitinit Argumentsinit Usage Exampleadd_ruleadd_rule Argumentsadd_rule Usage Exampleadd_resultadd_result Argumentsadd_result Usage Exampleget_sarifget_sarif Usage Examplesavesave Argumentssave Usage Exampleget_table_resultget_table_result Argumentsto_tableto_table Argumentsto_table Usage Exampleto_csvto_csv Argumentsto_csv Usage Examplerfilter_outrfilter_out Argumentsrfilter_out Usage Examplerfilter_onlyrfilter_only Argumentsrfilter_only Usage Examplefind_resultsfind_results Argumentsfind_results Usage Examplefind_rulefind_rule Argumentsfind_rule Usage Exampleaggregate_resultsaggregate_results Argumentsaggregate_results Usage Exampleverify_sarifverify_sarif Argumentsverify_sarif Usage ExampleFeaturesGenerate SARIF files with rules and resultsFilter out results from a SARIFConvert SARIF to a table or CSVFind results and rules from a SARIFAggregate results from a SARIF into one result for every rule in a runVerify a SARIF complies with its schemaInstallationSimply run the following command to install it:pipinstallsimple-sarifTo create a simple-sarif object, run:importsimple_sarifvar=simple_sarif.Sarif()Function DescriptionsNOTE: All arguments are required unless otherwise stated.initinit runs when a sarif object is created usingvar = 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 Argumentsfile="FILENAME" (optional)Default isNone.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.validate=[True/False] (optional)Default isTrue.This tells the code whether it should validate that the given SARIF file matches its schema. If not, the object won't be created.recreate=[True/False] (optional)Default isFalse. (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.init Usage Examplevar=simple_sarif.Sarif(file="sarif.json",validate=True,recreate=True)add_ruleadd_rule appends a new rule to the self.sarif variable. If the ruleID already exists, the rule will be overwritten.add_rule ArgumentsnameGives the rule a name (e.g. Secrets Found)ruleIdGives the rule a ruleId. RuleIds usually look likeGGS001orfound.secrets.shortDescriptionAdds a concise description of what the rule is for.fullDescriptionA longer description of the rule's purpose.messageStringsA 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 ExampleNote: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_resultAdds a result based on some provided ruleID. The ruleID must be one that matches a rule inside of the SARIF.add_result ArgumentsruleIdThis functions the same as in add_rule. It must match a ruleID inside of the rules section of the SARIF file.levelMarks whether the result is a pass or fail, indicated by "note" or "error".message_idThe 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. Seeherefor 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 Examplevar.add_result("test.rule","note","Successful run of '{0}'",["test"],{"run_type":"local"},[{"physicalLocation":{"artifactLocation":{"uri":"file///path"},"region":{"startLine":5,"startColumn":6}}}])get_sarifReturns entire self.sarif object to be stored and manipulated manually.get_sarif Usage Examplesarif_data=var.get_sarif()saveSaves self.sarif data to a file.save Argumentsvalidate=[True/False]Defaults toFalse.Tells the script whether it should check that the SARIF matches its schema before saving it to a file.filename="FILENAME" (optional if one was not given earlier)Defaults toNone.If a filename was not given when thesimple_sarifobject 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, thesavemethod will fail.save Usage Examplevar.save(validate=True,filename="sarif.json")get_table_resultReturns given data as a dictionary.get_table_result ArgumentsruleName, ruleId, level, shortDescription, message, ruleProperties, and resultProperties were
all explained before. Seeadd_result argumentsandadd_rule arguments.to_tableConverts SARIF (Static Analysis Results Interchange Format) results to a table format.This function processes SARIF results from a SARIF-formatted report stored inself.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 Argumentsadd_properties=[True/False]Defaults toTrue.Determines if the function will check for thepropertiesfield, and if it's found, add it to the table.to_table Usage Exampletable=var.to_table(add_properties=False)to_csvConverts 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 ArgumentsfilenameA string containing the name of the CSV file being written to.add_properties=[True/False]Defaults toTrue.Sets add_properties value for the to_table method.to_csv Usage Examplevar.to_csv(filename="sarif.csv",add_properties=False)rfilter_outFilters out results from the self.sarif object based on provided ruleIDs and levels.
If both ruleIDs and levels have a value, it willONLYfilter out rules that match both.rfilter_out ArgumentsNOTE: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 thesavefunction, a filename is required if one was not set during initialization.rfilter_out Usage Examplevar.rfilter_out(ruleIDs=["test.rule","test.rules"],levels=["note"],filename=None)rfilter_onlyFilters 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 matchingbothto be deleted.rfilter_only ArgumentsSeehere.rfilter_only Usage Examplevar.rfilter_only(ruleIDs=["test.rule"],levels=["note","error"],filename="sarif.json")find_resultsReturns 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 ArgumentsSeehere.find_results Usage Exampleresults=var.find_results(ruleIDs=["test.rule"],levels=["error"])find_ruleReturns a list of rules matching given ruleIDs.find_rule ArgumentsruleIDsA list of ruleIDs to search for.filename (optional)Seehere.find_rule Usage Examplerules=var.find_rule(ruleIDs=["test.rules","test.rule"],filename="sarif.json")aggregate_resultsGathers 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 Argumentsfail_type=["one"/"all"]Defaults to"one".A fail_type of"one"means that the final result for the rule will beerrorif one of the results was anerror.A fail_type of"all"will cause the end result to beerroronly if every result was anerror.remove_aggregated=[True/False]Defaults toTrue.Tells the function if it should delete the results it aggregates.filename (optional)Seehere.aggregate_results Usage Examplevar.aggregate_results(fail_type="all",remove_aggregated=False,filename=None)verify_sarifChecks 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$schemafield.If no schema is found or the link is invalid, the method will not raise an error, instead warning the user and returningTrue.
If the SARIF fails validation, the script will returnFalse, indicating an error.verify_sarif Argumentsfilename (optional)Seehere.verify_sarif Usage Examplevalidation_result=var.verify_sarif(filename="sarif.json")ifnotvalidation_result:print("SARIF validation failed.")