diff --git a/CMakeLists.txt b/CMakeLists.txt index 0294463..098c145 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -103,6 +103,7 @@ endif() add_subdirectory(core) add_subdirectory(coro) add_subdirectory(graph) +add_subdirectory(sarif) option(GAP_ENABLE_MLIR "Enable MLIR support" OFF) @@ -167,6 +168,7 @@ if (GAP_INSTALL) install_gap_target(gap-settings core) install_gap_target(gap-coro coro) install_gap_target(gap-graph graph) + install_gap_target(gap-sarif sarif) if (${GAP_ENABLE_MLIR}) install_gap_target(gap-mlir mlir) diff --git a/sarif/CMakeLists.txt b/sarif/CMakeLists.txt new file mode 100644 index 0000000..eb3d514 --- /dev/null +++ b/sarif/CMakeLists.txt @@ -0,0 +1,10 @@ +# Copyright (c) 2024-present, Trail of Bits, Inc. All rights reserved. + +find_package(nlohmann_json CONFIG REQUIRED) + +add_headers(sarif GAP_SARIF_HEADERS + sarif.hpp +) + +add_gap_library(gap-sarif "${GAP_SARIF_HEADERS}") +target_link_libraries(gap-sarif INTERFACE nlohmann_json::nlohmann_json) \ No newline at end of file diff --git a/sarif/include/gap/sarif/sarif.hpp b/sarif/include/gap/sarif/sarif.hpp new file mode 100644 index 0000000..38eebfe --- /dev/null +++ b/sarif/include/gap/sarif/sarif.hpp @@ -0,0 +1,2756 @@ +// Copyright 2024-present, Trail of Bits, Inc. + +#pragma once + +#include +#include +#include +#include +#include + +namespace gap::sarif::definitions +{ +enum class version_enum { + k2_1_0, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(version_enum, { + {version_enum::k2_1_0, "2.1.0"}, +}) +struct run_struct; +struct external_properties_struct; + +// +// Key/value pairs that provide additional information about the object. +// +struct property_bag_struct { + // + // A set of distinct strings that provide additional information. + // + std::vector tags; +}; + +void to_json(nlohmann::json &, const property_bag_struct &); +void from_json(const nlohmann::json &, property_bag_struct &); + +// +// Static Analysis Results Format (SARIF) Version 2.1.0 JSON Schema: a standard format for the output of static analysis tools. +// +struct root_struct { + // + // The SARIF format version of this log file. + // + version_enum version; + + // + // The set of runs contained in this log file. + // + std::vector runs; + + // + // References to external property files that share data between runs. + // + std::vector inlineExternalProperties; + + // + // Key/value pairs that provide additional information about the log file. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const root_struct &); +void from_json(const nlohmann::json &, root_struct &); + +// +// A physical or virtual address, or a range of addresses, in an 'addressable region' (memory or a binary file). +// +struct address_struct { + // + // The address expressed as a byte offset from the start of the addressable region. + // + int64_t absoluteAddress; + + // + // The address expressed as a byte offset from the absolute address of the top-most parent object. + // + int64_t relativeAddress; + + // + // The number of bytes in this range of addresses. + // + int64_t length; + + // + // An open-ended string that identifies the address kind. 'data', 'function', 'header','instruction', 'module', 'page', 'section', 'segment', 'stack', 'stackFrame', 'table' are well-known values. + // + std::string kind; + + // + // A name that is associated with the address, e.g., '.text'. + // + std::string name; + + // + // A human-readable fully qualified name that is associated with the address. + // + std::string fullyQualifiedName; + + // + // The byte offset of this address from the absolute or relative address of the parent object. + // + int64_t offsetFromParent; + + // + // The index within run.addresses of the cached object for this address. + // + int64_t index; + + // + // The index within run.addresses of the parent object. + // + int64_t parentIndex; + + // + // Key/value pairs that provide additional information about the address. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const address_struct &); +void from_json(const nlohmann::json &, address_struct &); + +// +// Encapsulates a message intended to be read by the end user. +// +struct message_struct { + // + // A plain text message string. + // + std::string text; + + // + // A Markdown message string. + // + std::string markdown; + + // + // The identifier for this message. + // + std::string id; + + // + // An array of strings to substitute into the message string. + // + std::vector arguments; + + // + // Key/value pairs that provide additional information about the message. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const message_struct &); +void from_json(const nlohmann::json &, message_struct &); + +// +// Specifies the location of an artifact. +// +struct artifact_location_struct { + // + // A string containing a valid relative or absolute URI. + // + std::string uri; + + // + // A string which indirectly specifies the absolute URI with respect to which a relative URI in the "uri" property is interpreted. + // + std::string uriBaseId; + + // + // The index within the run artifacts array of the artifact object associated with the artifact location. + // + int64_t index; + + // + // A short description of the artifact location. + // + message_struct description; + + // + // Key/value pairs that provide additional information about the artifact location. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const artifact_location_struct &); +void from_json(const nlohmann::json &, artifact_location_struct &); + +enum class roles_enum { + kAnalysisTarget, + kAttachment, + kResponseFile, + kResultFile, + kStandardStream, + kTracedFile, + kUnmodified, + kModified, + kAdded, + kDeleted, + kRenamed, + kUncontrolled, + kDriver, + kExtension, + kTranslation, + kTaxonomy, + kPolicy, + kReferencedOnCommandLine, + kMemoryContents, + kDirectory, + kUserSpecifiedConfiguration, + kToolSpecifiedConfiguration, + kDebugOutputFile, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(roles_enum, { + {roles_enum::kAnalysisTarget, "analysisTarget"}, + {roles_enum::kAttachment, "attachment"}, + {roles_enum::kResponseFile, "responseFile"}, + {roles_enum::kResultFile, "resultFile"}, + {roles_enum::kStandardStream, "standardStream"}, + {roles_enum::kTracedFile, "tracedFile"}, + {roles_enum::kUnmodified, "unmodified"}, + {roles_enum::kModified, "modified"}, + {roles_enum::kAdded, "added"}, + {roles_enum::kDeleted, "deleted"}, + {roles_enum::kRenamed, "renamed"}, + {roles_enum::kUncontrolled, "uncontrolled"}, + {roles_enum::kDriver, "driver"}, + {roles_enum::kExtension, "extension"}, + {roles_enum::kTranslation, "translation"}, + {roles_enum::kTaxonomy, "taxonomy"}, + {roles_enum::kPolicy, "policy"}, + {roles_enum::kReferencedOnCommandLine, "referencedOnCommandLine"}, + {roles_enum::kMemoryContents, "memoryContents"}, + {roles_enum::kDirectory, "directory"}, + {roles_enum::kUserSpecifiedConfiguration, "userSpecifiedConfiguration"}, + {roles_enum::kToolSpecifiedConfiguration, "toolSpecifiedConfiguration"}, + {roles_enum::kDebugOutputFile, "debugOutputFile"}, +}) + +// +// A message string or message format string rendered in multiple formats. +// +struct multiformat_message_string_struct { + // + // A plain text message string or format string. + // + std::string text; + + // + // A Markdown message string or format string. + // + std::string markdown; + + // + // Key/value pairs that provide additional information about the message. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const multiformat_message_string_struct &); +void from_json(const nlohmann::json &, multiformat_message_string_struct &); + +// +// Represents the contents of an artifact. +// +struct artifact_content_struct { + // + // UTF-8-encoded content from a text artifact. + // + std::string text; + + // + // MIME Base64-encoded content from a binary artifact, or from a text artifact in its original encoding. + // + std::string binary; + + // + // An alternate rendered representation of the artifact (e.g., a decompiled representation of a binary region). + // + multiformat_message_string_struct rendered; + + // + // Key/value pairs that provide additional information about the artifact content. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const artifact_content_struct &); +void from_json(const nlohmann::json &, artifact_content_struct &); + +// +// A single artifact. In some cases, this artifact might be nested within another artifact. +// +struct artifact_struct { + // + // A short description of the artifact. + // + message_struct description; + + // + // The location of the artifact. + // + artifact_location_struct location; + + // + // Identifies the index of the immediate parent of the artifact, if this artifact is nested. + // + int64_t parentIndex; + + // + // The offset in bytes of the artifact within its containing artifact. + // + int64_t offset; + + // + // The length of the artifact in bytes. + // + int64_t length; + + // + // The role or roles played by the artifact in the analysis. + // + std::vector roles; + + // + // The MIME type (RFC 2045) of the artifact. + // + std::string mimeType; + + // + // The contents of the artifact. + // + artifact_content_struct contents; + + // + // Specifies the encoding for an artifact object that refers to a text file. + // + std::string encoding; + + // + // Specifies the source language for any artifact object that refers to a text file that contains source code. + // + std::string sourceLanguage; + + // + // A dictionary, each of whose keys is the name of a hash function and each of whose values is the hashed value of the artifact produced by the specified hash function. + // + std::unordered_map hashes; + + // + // The Coordinated Universal Time (UTC) date and time at which the artifact was most recently modified. See "Date/time properties" in the SARIF spec for the required format. + // + std::string lastModifiedTimeUtc; + + // + // Key/value pairs that provide additional information about the artifact. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const artifact_struct &); +void from_json(const nlohmann::json &, artifact_struct &); +struct replacement_struct; + +// +// A change to a single artifact. +// +struct artifact_change_struct { + // + // The location of the artifact to change. + // + artifact_location_struct artifactLocation; + + // + // An array of replacement objects, each of which represents the replacement of a single region in a single artifact specified by 'artifactLocation'. + // + std::vector replacements; + + // + // Key/value pairs that provide additional information about the change. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const artifact_change_struct &); +void from_json(const nlohmann::json &, artifact_change_struct &); +struct region_struct; +struct rectangle_struct; + +// +// An artifact relevant to a result. +// +struct attachment_struct { + // + // A message describing the role played by the attachment. + // + message_struct description; + + // + // The location of the attachment. + // + artifact_location_struct artifactLocation; + + // + // An array of regions of interest within the attachment. + // + std::vector regions; + + // + // An array of rectangles specifying areas of interest within the image. + // + std::vector rectangles; + + // + // Key/value pairs that provide additional information about the attachment. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const attachment_struct &); +void from_json(const nlohmann::json &, attachment_struct &); +struct thread_flow_struct; + +// +// A set of threadFlows which together describe a pattern of code execution relevant to detecting a result. +// +struct code_flow_struct { + // + // A message relevant to the code flow. + // + message_struct message; + + // + // An array of one or more unique threadFlow objects, each of which describes the progress of a program through a thread of execution. + // + std::vector threadFlows; + + // + // Key/value pairs that provide additional information about the code flow. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const code_flow_struct &); +void from_json(const nlohmann::json &, code_flow_struct &); + +enum class level_enum { + kNone, + kNote, + kWarning, + kError, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(level_enum, { + {level_enum::kNone, "none"}, + {level_enum::kNote, "note"}, + {level_enum::kWarning, "warning"}, + {level_enum::kError, "error"}, +}) + +// +// Information about a rule or notification that can be configured at runtime. +// +struct reporting_configuration_struct { + // + // Specifies whether the report may be produced during the scan. + // + bool enabled; + + // + // Specifies the failure level for the report. + // + level_enum level; + + // + // Specifies the relative priority of the report. Used for analysis output only. + // + double rank; + + // + // Contains configuration information specific to a report. + // + property_bag_struct parameters; + + // + // Key/value pairs that provide additional information about the reporting configuration. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const reporting_configuration_struct &); +void from_json(const nlohmann::json &, reporting_configuration_struct &); + +// +// Identifies a particular toolComponent object, either the driver or an extension. +// +struct tool_component_reference_struct { + // + // The 'name' property of the referenced toolComponent. + // + std::string name; + + // + // An index into the referenced toolComponent in tool.extensions. + // + int64_t index; + + // + // The 'guid' property of the referenced toolComponent. + // + std::string guid; + + // + // Key/value pairs that provide additional information about the toolComponentReference. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const tool_component_reference_struct &); +void from_json(const nlohmann::json &, tool_component_reference_struct &); + +// +// Information about how to locate a relevant reporting descriptor. +// +struct reporting_descriptor_reference_struct { + // + // The id of the descriptor. + // + std::string id; + + // + // The index into an array of descriptors in toolComponent.ruleDescriptors, toolComponent.notificationDescriptors, or toolComponent.taxonomyDescriptors, depending on context. + // + int64_t index; + + // + // A guid that uniquely identifies the descriptor. + // + std::string guid; + + // + // A reference used to locate the toolComponent associated with the descriptor. + // + tool_component_reference_struct toolComponent; + + // + // Key/value pairs that provide additional information about the reporting descriptor reference. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const reporting_descriptor_reference_struct &); +void from_json(const nlohmann::json &, reporting_descriptor_reference_struct &); + +// +// Information about how a specific rule or notification was reconfigured at runtime. +// +struct configuration_override_struct { + // + // Specifies how the rule or notification was configured during the scan. + // + reporting_configuration_struct configuration; + + // + // A reference used to locate the descriptor whose configuration was overridden. + // + reporting_descriptor_reference_struct descriptor; + + // + // Key/value pairs that provide additional information about the configuration override. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const configuration_override_struct &); +void from_json(const nlohmann::json &, configuration_override_struct &); +struct reporting_descriptor_struct; + +enum class contents_enum { + kLocalizedData, + kNonLocalizedData, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(contents_enum, { + {contents_enum::kLocalizedData, "localizedData"}, + {contents_enum::kNonLocalizedData, "nonLocalizedData"}, +}) + +// +// Provides additional metadata related to translation. +// +struct translation_metadata_struct { + // + // The name associated with the translation metadata. + // + std::string name; + + // + // The full name associated with the translation metadata. + // + std::string fullName; + + // + // A brief description of the translation metadata. + // + multiformat_message_string_struct shortDescription; + + // + // A comprehensive description of the translation metadata. + // + multiformat_message_string_struct fullDescription; + + // + // The absolute URI from which the translation metadata can be downloaded. + // + std::string downloadUri; + + // + // The absolute URI from which information related to the translation metadata can be downloaded. + // + std::string informationUri; + + // + // Key/value pairs that provide additional information about the translation metadata. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const translation_metadata_struct &); +void from_json(const nlohmann::json &, translation_metadata_struct &); + +// +// A component, such as a plug-in or the driver, of the analysis tool that was run. +// +struct tool_component_struct { + // + // A unique identifer for the tool component in the form of a GUID. + // + std::string guid; + + // + // The name of the tool component. + // + std::string name; + + // + // The organization or company that produced the tool component. + // + std::string organization; + + // + // A product suite to which the tool component belongs. + // + std::string product; + + // + // A localizable string containing the name of the suite of products to which the tool component belongs. + // + std::string productSuite; + + // + // A brief description of the tool component. + // + multiformat_message_string_struct shortDescription; + + // + // A comprehensive description of the tool component. + // + multiformat_message_string_struct fullDescription; + + // + // The name of the tool component along with its version and any other useful identifying information, such as its locale. + // + std::string fullName; + + // + // The tool component version, in whatever format the component natively provides. + // + std::string version; + + // + // The tool component version in the format specified by Semantic Versioning 2.0. + // + std::string semanticVersion; + + // + // The binary version of the tool component's primary executable file expressed as four non-negative integers separated by a period (for operating systems that express file versions in this way). + // + std::string dottedQuadFileVersion; + + // + // A string specifying the UTC date (and optionally, the time) of the component's release. + // + std::string releaseDateUtc; + + // + // The absolute URI from which the tool component can be downloaded. + // + std::string downloadUri; + + // + // The absolute URI at which information about this version of the tool component can be found. + // + std::string informationUri; + + // + // A dictionary, each of whose keys is a resource identifier and each of whose values is a multiformatMessageString object, which holds message strings in plain text and (optionally) Markdown format. The strings can include placeholders, which can be used to construct a message in combination with an arbitrary number of additional string arguments. + // + std::unordered_map globalMessageStrings; + + // + // An array of reportingDescriptor objects relevant to the notifications related to the configuration and runtime execution of the tool component. + // + std::vector notifications; + + // + // An array of reportingDescriptor objects relevant to the analysis performed by the tool component. + // + std::vector rules; + + // + // An array of reportingDescriptor objects relevant to the definitions of both standalone and tool-defined taxonomies. + // + std::vector taxa; + + // + // An array of the artifactLocation objects associated with the tool component. + // + std::vector locations; + + // + // The language of the messages emitted into the log file during this run (expressed as an ISO 639-1 two-letter lowercase language code) and an optional region (expressed as an ISO 3166-1 two-letter uppercase subculture code associated with a country or region). The casing is recommended but not required (in order for this data to conform to RFC5646). + // + std::string language; + + // + // The kinds of data contained in this object. + // + std::vector contents; + + // + // Specifies whether this object contains a complete definition of the localizable and/or non-localizable data for this component, as opposed to including only data that is relevant to the results persisted to this log file. + // + bool isComprehensive; + + // + // The semantic version of the localized strings defined in this component; maintained by components that provide translations. + // + std::string localizedDataSemanticVersion; + + // + // The minimum value of localizedDataSemanticVersion required in translations consumed by this component; used by components that consume translations. + // + std::string minimumRequiredLocalizedDataSemanticVersion; + + // + // The component which is strongly associated with this component. For a translation, this refers to the component which has been translated. For an extension, this is the driver that provides the extension's plugin model. + // + tool_component_reference_struct associatedComponent; + + // + // Translation metadata, required for a translation, not populated by other component types. + // + translation_metadata_struct translationMetadata; + + // + // An array of toolComponentReference objects to declare the taxonomies supported by the tool component. + // + std::vector supportedTaxonomies; + + // + // Key/value pairs that provide additional information about the tool component. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const tool_component_struct &); +void from_json(const nlohmann::json &, tool_component_struct &); + +// +// The analysis tool that was run. +// +struct tool_struct { + // + // The analysis tool that was run. + // + tool_component_struct driver; + + // + // Tool extensions that contributed to or reconfigured the analysis tool that was run. + // + std::vector extensions; + + // + // Key/value pairs that provide additional information about the tool. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const tool_struct &); +void from_json(const nlohmann::json &, tool_struct &); +struct notification_struct; + +// +// The runtime environment of the analysis tool run. +// +struct invocation_struct { + // + // The command line used to invoke the tool. + // + std::string commandLine; + + // + // An array of strings, containing in order the command line arguments passed to the tool from the operating system. + // + std::vector arguments; + + // + // The locations of any response files specified on the tool's command line. + // + std::vector responseFiles; + + // + // The Coordinated Universal Time (UTC) date and time at which the run started. See "Date/time properties" in the SARIF spec for the required format. + // + std::string startTimeUtc; + + // + // The Coordinated Universal Time (UTC) date and time at which the run ended. See "Date/time properties" in the SARIF spec for the required format. + // + std::string endTimeUtc; + + // + // The process exit code. + // + int64_t exitCode; + + // + // An array of configurationOverride objects that describe rules related runtime overrides. + // + std::vector ruleConfigurationOverrides; + + // + // An array of configurationOverride objects that describe notifications related runtime overrides. + // + std::vector notificationConfigurationOverrides; + + // + // A list of runtime conditions detected by the tool during the analysis. + // + std::vector toolExecutionNotifications; + + // + // A list of conditions detected by the tool that are relevant to the tool's configuration. + // + std::vector toolConfigurationNotifications; + + // + // The reason for the process exit. + // + std::string exitCodeDescription; + + // + // The name of the signal that caused the process to exit. + // + std::string exitSignalName; + + // + // The numeric value of the signal that caused the process to exit. + // + int64_t exitSignalNumber; + + // + // The reason given by the operating system that the process failed to start. + // + std::string processStartFailureMessage; + + // + // Specifies whether the tool's execution completed successfully. + // + bool executionSuccessful; + + // + // The machine that hosted the analysis tool run. + // + std::string machine; + + // + // The account that ran the analysis tool. + // + std::string account; + + // + // The process id for the analysis tool run. + // + int64_t processId; + + // + // An absolute URI specifying the location of the analysis tool's executable. + // + artifact_location_struct executableLocation; + + // + // The working directory for the analysis tool run. + // + artifact_location_struct workingDirectory; + + // + // The environment variables associated with the analysis tool process, expressed as key/value pairs. + // + std::unordered_map environmentVariables; + + // + // A file containing the standard input stream to the process that was invoked. + // + artifact_location_struct stdin; + + // + // A file containing the standard output stream from the process that was invoked. + // + artifact_location_struct stdout; + + // + // A file containing the standard error stream from the process that was invoked. + // + artifact_location_struct stderr; + + // + // A file containing the interleaved standard output and standard error stream from the process that was invoked. + // + artifact_location_struct stdoutStderr; + + // + // Key/value pairs that provide additional information about the invocation. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const invocation_struct &); +void from_json(const nlohmann::json &, invocation_struct &); + +// +// Describes how a converter transformed the output of a static analysis tool from the analysis tool's native output format into the SARIF format. +// +struct conversion_struct { + // + // A tool object that describes the converter. + // + tool_struct tool; + + // + // An invocation object that describes the invocation of the converter. + // + invocation_struct invocation; + + // + // The locations of the analysis tool's per-run log files. + // + std::vector analysisToolLogFiles; + + // + // Key/value pairs that provide additional information about the conversion. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const conversion_struct &); +void from_json(const nlohmann::json &, conversion_struct &); + +// +// Represents a directed edge in a graph. +// +struct edge_struct { + // + // A string that uniquely identifies the edge within its graph. + // + std::string id; + + // + // A short description of the edge. + // + message_struct label; + + // + // Identifies the source node (the node at which the edge starts). + // + std::string sourceNodeId; + + // + // Identifies the target node (the node at which the edge ends). + // + std::string targetNodeId; + + // + // Key/value pairs that provide additional information about the edge. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const edge_struct &); +void from_json(const nlohmann::json &, edge_struct &); + +// +// Represents the traversal of a single edge during a graph traversal. +// +struct edge_traversal_struct { + // + // Identifies the edge being traversed. + // + std::string edgeId; + + // + // A message to display to the user as the edge is traversed. + // + message_struct message; + + // + // The values of relevant expressions after the edge has been traversed. + // + std::unordered_map finalState; + + // + // The number of edge traversals necessary to return from a nested graph. + // + int64_t stepOverEdgeCount; + + // + // Key/value pairs that provide additional information about the edge traversal. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const edge_traversal_struct &); +void from_json(const nlohmann::json &, edge_traversal_struct &); +struct stack_frame_struct; + +// +// A call stack that is relevant to a result. +// +struct stack_struct { + // + // A message relevant to this call stack. + // + message_struct message; + + // + // An array of stack frames that represents a sequence of calls, rendered in reverse chronological order, that comprise the call stack. + // + std::vector frames; + + // + // Key/value pairs that provide additional information about the stack. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const stack_struct &); +void from_json(const nlohmann::json &, stack_struct &); +struct exception_struct; + +// +// Describes a runtime exception encountered during the execution of an analysis tool. +// +struct exception_struct { + // + // A string that identifies the kind of exception, for example, the fully qualified type name of an object that was thrown, or the symbolic name of a signal. + // + std::string kind; + + // + // A message that describes the exception. + // + std::string message; + + // + // The sequence of function calls leading to the exception. + // + stack_struct stack; + + // + // An array of exception objects each of which is considered a cause of this exception. + // + std::vector innerExceptions; + + // + // Key/value pairs that provide additional information about the exception. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const exception_struct &); +void from_json(const nlohmann::json &, exception_struct &); +struct graph_struct; +struct logical_location_struct; +struct thread_flow_location_struct; +struct result_struct; +struct web_request_struct; +struct web_response_struct; + +// +// The top-level element of an external property file. +// +struct external_properties_struct { + // + // The URI of the JSON schema corresponding to the version of the external property file format. + // + std::string schema; + + // + // The SARIF format version of this external properties object. + // + version_enum version; + + // + // A stable, unique identifer for this external properties object, in the form of a GUID. + // + std::string guid; + + // + // A stable, unique identifer for the run associated with this external properties object, in the form of a GUID. + // + std::string runGuid; + + // + // A conversion object that will be merged with a separate run. + // + conversion_struct conversion; + + // + // An array of graph objects that will be merged with a separate run. + // + std::vector graphs; + + // + // Key/value pairs that provide additional information that will be merged with a separate run. + // + property_bag_struct externalizedProperties; + + // + // An array of artifact objects that will be merged with a separate run. + // + std::vector artifacts; + + // + // Describes the invocation of the analysis tool that will be merged with a separate run. + // + std::vector invocations; + + // + // An array of logical locations such as namespaces, types or functions that will be merged with a separate run. + // + std::vector logicalLocations; + + // + // An array of threadFlowLocation objects that will be merged with a separate run. + // + std::vector threadFlowLocations; + + // + // An array of result objects that will be merged with a separate run. + // + std::vector results; + + // + // Tool taxonomies that will be merged with a separate run. + // + std::vector taxonomies; + + // + // The analysis tool object that will be merged with a separate run. + // + tool_component_struct driver; + + // + // Tool extensions that will be merged with a separate run. + // + std::vector extensions; + + // + // Tool policies that will be merged with a separate run. + // + std::vector policies; + + // + // Tool translations that will be merged with a separate run. + // + std::vector translations; + + // + // Addresses that will be merged with a separate run. + // + std::vector addresses; + + // + // Requests that will be merged with a separate run. + // + std::vector webRequests; + + // + // Responses that will be merged with a separate run. + // + std::vector webResponses; + + // + // Key/value pairs that provide additional information about the external properties. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const external_properties_struct &); +void from_json(const nlohmann::json &, external_properties_struct &); + +// +// Contains information that enables a SARIF consumer to locate the external property file that contains the value of an externalized property associated with the run. +// +struct external_property_file_reference_struct { + // + // The location of the external property file. + // + artifact_location_struct location; + + // + // A stable, unique identifer for the external property file in the form of a GUID. + // + std::string guid; + + // + // A non-negative integer specifying the number of items contained in the external property file. + // + int64_t itemCount; + + // + // Key/value pairs that provide additional information about the external property file. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const external_property_file_reference_struct &); +void from_json(const nlohmann::json &, external_property_file_reference_struct &); + +// +// References to external property files that should be inlined with the content of a root log file. +// +struct external_property_file_references_struct { + // + // An external property file containing a run.conversion object to be merged with the root log file. + // + external_property_file_reference_struct conversion; + + // + // An array of external property files containing a run.graphs object to be merged with the root log file. + // + std::vector graphs; + + // + // An external property file containing a run.properties object to be merged with the root log file. + // + external_property_file_reference_struct externalizedProperties; + + // + // An array of external property files containing run.artifacts arrays to be merged with the root log file. + // + std::vector artifacts; + + // + // An array of external property files containing run.invocations arrays to be merged with the root log file. + // + std::vector invocations; + + // + // An array of external property files containing run.logicalLocations arrays to be merged with the root log file. + // + std::vector logicalLocations; + + // + // An array of external property files containing run.threadFlowLocations arrays to be merged with the root log file. + // + std::vector threadFlowLocations; + + // + // An array of external property files containing run.results arrays to be merged with the root log file. + // + std::vector results; + + // + // An array of external property files containing run.taxonomies arrays to be merged with the root log file. + // + std::vector taxonomies; + + // + // An array of external property files containing run.addresses arrays to be merged with the root log file. + // + std::vector addresses; + + // + // An external property file containing a run.driver object to be merged with the root log file. + // + external_property_file_reference_struct driver; + + // + // An array of external property files containing run.extensions arrays to be merged with the root log file. + // + std::vector extensions; + + // + // An array of external property files containing run.policies arrays to be merged with the root log file. + // + std::vector policies; + + // + // An array of external property files containing run.translations arrays to be merged with the root log file. + // + std::vector translations; + + // + // An array of external property files containing run.requests arrays to be merged with the root log file. + // + std::vector webRequests; + + // + // An array of external property files containing run.responses arrays to be merged with the root log file. + // + std::vector webResponses; + + // + // Key/value pairs that provide additional information about the external property files. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const external_property_file_references_struct &); +void from_json(const nlohmann::json &, external_property_file_references_struct &); + +// +// A proposed fix for the problem represented by a result object. A fix specifies a set of artifacts to modify. For each artifact, it specifies a set of bytes to remove, and provides a set of new bytes to replace them. +// +struct fix_struct { + // + // A message that describes the proposed fix, enabling viewers to present the proposed change to an end user. + // + message_struct description; + + // + // One or more artifact changes that comprise a fix for a result. + // + std::vector artifactChanges; + + // + // Key/value pairs that provide additional information about the fix. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const fix_struct &); +void from_json(const nlohmann::json &, fix_struct &); +struct node_struct; + +// +// A network of nodes and directed edges that describes some aspect of the structure of the code (for example, a call graph). +// +struct graph_struct { + // + // A description of the graph. + // + message_struct description; + + // + // An array of node objects representing the nodes of the graph. + // + std::vector nodes; + + // + // An array of edge objects representing the edges of the graph. + // + std::vector edges; + + // + // Key/value pairs that provide additional information about the graph. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const graph_struct &); +void from_json(const nlohmann::json &, graph_struct &); + +// +// Represents a path through a graph. +// +struct graph_traversal_struct { + // + // The index within the run.graphs to be associated with the result. + // + int64_t runGraphIndex; + + // + // The index within the result.graphs to be associated with the result. + // + int64_t resultGraphIndex; + + // + // A description of this graph traversal. + // + message_struct description; + + // + // Values of relevant expressions at the start of the graph traversal that may change during graph traversal. + // + std::unordered_map initialState; + + // + // Values of relevant expressions at the start of the graph traversal that remain constant for the graph traversal. + // + std::unordered_map immutableState; + + // + // The sequences of edges traversed by this graph traversal. + // + std::vector edgeTraversals; + + // + // Key/value pairs that provide additional information about the graph traversal. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const graph_traversal_struct &); +void from_json(const nlohmann::json &, graph_traversal_struct &); + +// +// A region within an artifact where a result was detected. +// +struct region_struct { + // + // The line number of the first character in the region. + // + int64_t startLine; + + // + // The column number of the first character in the region. + // + int64_t startColumn; + + // + // The line number of the last character in the region. + // + int64_t endLine; + + // + // The column number of the character following the end of the region. + // + int64_t endColumn; + + // + // The zero-based offset from the beginning of the artifact of the first character in the region. + // + int64_t charOffset; + + // + // The length of the region in characters. + // + int64_t charLength; + + // + // The zero-based offset from the beginning of the artifact of the first byte in the region. + // + int64_t byteOffset; + + // + // The length of the region in bytes. + // + int64_t byteLength; + + // + // The portion of the artifact contents within the specified region. + // + artifact_content_struct snippet; + + // + // A message relevant to the region. + // + message_struct message; + + // + // Specifies the source language, if any, of the portion of the artifact specified by the region object. + // + std::string sourceLanguage; + + // + // Key/value pairs that provide additional information about the region. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const region_struct &); +void from_json(const nlohmann::json &, region_struct &); + +// +// A physical location relevant to a result. Specifies a reference to a programming artifact together with a range of bytes or characters within that artifact. +// +struct physical_location_struct { + // + // The address of the location. + // + address_struct address; + + // + // The location of the artifact. + // + artifact_location_struct artifactLocation; + + // + // Specifies a portion of the artifact. + // + region_struct region; + + // + // Specifies a portion of the artifact that encloses the region. Allows a viewer to display additional context around the region. + // + region_struct contextRegion; + + // + // Key/value pairs that provide additional information about the physical location. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const physical_location_struct &); +void from_json(const nlohmann::json &, physical_location_struct &); +struct location_relationship_struct; + +// +// A location within a programming artifact. +// +struct location_struct { + // + // Value that distinguishes this location from all other locations within a single result object. + // + int64_t id; + + // + // Identifies the artifact and region. + // + physical_location_struct physicalLocation; + + // + // The logical locations associated with the result. + // + std::vector logicalLocations; + + // + // A message relevant to the location. + // + message_struct message; + + // + // A set of regions relevant to the location. + // + std::vector annotations; + + // + // An array of objects that describe relationships between this location and others. + // + std::vector relationships; + + // + // Key/value pairs that provide additional information about the location. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const location_struct &); +void from_json(const nlohmann::json &, location_struct &); + +// +// Information about the relation of one location to another. +// +struct location_relationship_struct { + // + // A reference to the related location. + // + int64_t target; + + // + // A set of distinct strings that categorize the relationship. Well-known kinds include 'includes', 'isIncludedBy' and 'relevant'. + // + std::vector kinds; + + // + // A description of the location relationship. + // + message_struct description; + + // + // Key/value pairs that provide additional information about the location relationship. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const location_relationship_struct &); +void from_json(const nlohmann::json &, location_relationship_struct &); + +// +// A logical location of a construct that produced a result. +// +struct logical_location_struct { + // + // Identifies the construct in which the result occurred. For example, this property might contain the name of a class or a method. + // + std::string name; + + // + // The index within the logical locations array. + // + int64_t index; + + // + // The human-readable fully qualified name of the logical location. + // + std::string fullyQualifiedName; + + // + // The machine-readable name for the logical location, such as a mangled function name provided by a C++ compiler that encodes calling convention, return type and other details along with the function name. + // + std::string decoratedName; + + // + // Identifies the index of the immediate parent of the construct in which the result was detected. For example, this property might point to a logical location that represents the namespace that holds a type. + // + int64_t parentIndex; + + // + // The type of construct this logical location component refers to. Should be one of 'function', 'member', 'module', 'namespace', 'parameter', 'resource', 'returnType', 'type', 'variable', 'object', 'array', 'property', 'value', 'element', 'text', 'attribute', 'comment', 'declaration', 'dtd' or 'processingInstruction', if any of those accurately describe the construct. + // + std::string kind; + + // + // Key/value pairs that provide additional information about the logical location. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const logical_location_struct &); +void from_json(const nlohmann::json &, logical_location_struct &); + +// +// Represents a node in a graph. +// +struct node_struct { + // + // A string that uniquely identifies the node within its graph. + // + std::string id; + + // + // A short description of the node. + // + message_struct label; + + // + // A code location associated with the node. + // + location_struct location; + + // + // Array of child nodes. + // + std::vector children; + + // + // Key/value pairs that provide additional information about the node. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const node_struct &); +void from_json(const nlohmann::json &, node_struct &); + +// +// Describes a condition relevant to the tool itself, as opposed to being relevant to a target being analyzed by the tool. +// +struct notification_struct { + // + // The locations relevant to this notification. + // + std::vector locations; + + // + // A message that describes the condition that was encountered. + // + message_struct message; + + // + // A value specifying the severity level of the notification. + // + level_enum level; + + // + // The thread identifier of the code that generated the notification. + // + int64_t threadId; + + // + // The Coordinated Universal Time (UTC) date and time at which the analysis tool generated the notification. + // + std::string timeUtc; + + // + // The runtime exception, if any, relevant to this notification. + // + exception_struct exception; + + // + // A reference used to locate the descriptor relevant to this notification. + // + reporting_descriptor_reference_struct descriptor; + + // + // A reference used to locate the rule descriptor associated with this notification. + // + reporting_descriptor_reference_struct associatedRule; + + // + // Key/value pairs that provide additional information about the notification. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const notification_struct &); +void from_json(const nlohmann::json &, notification_struct &); + +// +// An area within an image. +// +struct rectangle_struct { + // + // The Y coordinate of the top edge of the rectangle, measured in the image's natural units. + // + double top; + + // + // The X coordinate of the left edge of the rectangle, measured in the image's natural units. + // + double left; + + // + // The Y coordinate of the bottom edge of the rectangle, measured in the image's natural units. + // + double bottom; + + // + // The X coordinate of the right edge of the rectangle, measured in the image's natural units. + // + double right; + + // + // A message relevant to the rectangle. + // + message_struct message; + + // + // Key/value pairs that provide additional information about the rectangle. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const rectangle_struct &); +void from_json(const nlohmann::json &, rectangle_struct &); + +// +// The replacement of a single region of an artifact. +// +struct replacement_struct { + // + // The region of the artifact to delete. + // + region_struct deletedRegion; + + // + // The content to insert at the location specified by the 'deletedRegion' property. + // + artifact_content_struct insertedContent; + + // + // Key/value pairs that provide additional information about the replacement. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const replacement_struct &); +void from_json(const nlohmann::json &, replacement_struct &); +struct reporting_descriptor_relationship_struct; + +// +// Metadata that describes a specific report produced by the tool, as part of the analysis it provides or its runtime reporting. +// +struct reporting_descriptor_struct { + // + // A stable, opaque identifier for the report. + // + std::string id; + + // + // An array of stable, opaque identifiers by which this report was known in some previous version of the analysis tool. + // + std::vector deprecatedIds; + + // + // A unique identifer for the reporting descriptor in the form of a GUID. + // + std::string guid; + + // + // An array of unique identifies in the form of a GUID by which this report was known in some previous version of the analysis tool. + // + std::vector deprecatedGuids; + + // + // A report identifier that is understandable to an end user. + // + std::string name; + + // + // An array of readable identifiers by which this report was known in some previous version of the analysis tool. + // + std::vector deprecatedNames; + + // + // A concise description of the report. Should be a single sentence that is understandable when visible space is limited to a single line of text. + // + multiformat_message_string_struct shortDescription; + + // + // A description of the report. Should, as far as possible, provide details sufficient to enable resolution of any problem indicated by the result. + // + multiformat_message_string_struct fullDescription; + + // + // A set of name/value pairs with arbitrary names. Each value is a multiformatMessageString object, which holds message strings in plain text and (optionally) Markdown format. The strings can include placeholders, which can be used to construct a message in combination with an arbitrary number of additional string arguments. + // + std::unordered_map messageStrings; + + // + // Default reporting configuration information. + // + reporting_configuration_struct defaultConfiguration; + + // + // A URI where the primary documentation for the report can be found. + // + std::string helpUri; + + // + // Provides the primary documentation for the report, useful when there is no online documentation. + // + multiformat_message_string_struct help; + + // + // An array of objects that describe relationships between this reporting descriptor and others. + // + std::vector relationships; + + // + // Key/value pairs that provide additional information about the report. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const reporting_descriptor_struct &); +void from_json(const nlohmann::json &, reporting_descriptor_struct &); + +// +// Information about the relation of one reporting descriptor to another. +// +struct reporting_descriptor_relationship_struct { + // + // A reference to the related reporting descriptor. + // + reporting_descriptor_reference_struct target; + + // + // A set of distinct strings that categorize the relationship. Well-known kinds include 'canPrecede', 'canFollow', 'willPrecede', 'willFollow', 'superset', 'subset', 'equal', 'disjoint', 'relevant', and 'incomparable'. + // + std::vector kinds; + + // + // A description of the reporting descriptor relationship. + // + message_struct description; + + // + // Key/value pairs that provide additional information about the reporting descriptor reference. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const reporting_descriptor_relationship_struct &); +void from_json(const nlohmann::json &, reporting_descriptor_relationship_struct &); + +enum class kind_enum { + kNotApplicable, + kPass, + kFail, + kReview, + kOpen, + kInformational, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(kind_enum, { + {kind_enum::kNotApplicable, "notApplicable"}, + {kind_enum::kPass, "pass"}, + {kind_enum::kFail, "fail"}, + {kind_enum::kReview, "review"}, + {kind_enum::kOpen, "open"}, + {kind_enum::kInformational, "informational"}, +}) +struct suppression_struct; + +enum class baseline_state_enum { + kNew, + kUnchanged, + kUpdated, + kAbsent, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(baseline_state_enum, { + {baseline_state_enum::kNew, "new"}, + {baseline_state_enum::kUnchanged, "unchanged"}, + {baseline_state_enum::kUpdated, "updated"}, + {baseline_state_enum::kAbsent, "absent"}, +}) + +// +// Contains information about how and when a result was detected. +// +struct result_provenance_struct { + // + // The Coordinated Universal Time (UTC) date and time at which the result was first detected. See "Date/time properties" in the SARIF spec for the required format. + // + std::string firstDetectionTimeUtc; + + // + // The Coordinated Universal Time (UTC) date and time at which the result was most recently detected. See "Date/time properties" in the SARIF spec for the required format. + // + std::string lastDetectionTimeUtc; + + // + // A GUID-valued string equal to the automationDetails.guid property of the run in which the result was first detected. + // + std::string firstDetectionRunGuid; + + // + // A GUID-valued string equal to the automationDetails.guid property of the run in which the result was most recently detected. + // + std::string lastDetectionRunGuid; + + // + // The index within the run.invocations array of the invocation object which describes the tool invocation that detected the result. + // + int64_t invocationIndex; + + // + // An array of physicalLocation objects which specify the portions of an analysis tool's output that a converter transformed into the result. + // + std::vector conversionSources; + + // + // Key/value pairs that provide additional information about the result. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const result_provenance_struct &); +void from_json(const nlohmann::json &, result_provenance_struct &); + +// +// Describes an HTTP request. +// +struct web_request_struct { + // + // The index within the run.webRequests array of the request object associated with this result. + // + int64_t index; + + // + // The request protocol. Example: 'http'. + // + std::string protocol; + + // + // The request version. Example: '1.1'. + // + std::string version; + + // + // The target of the request. + // + std::string target; + + // + // The HTTP method. Well-known values are 'GET', 'PUT', 'POST', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS', 'TRACE', 'CONNECT'. + // + std::string method; + + // + // The request headers. + // + std::unordered_map headers; + + // + // The request parameters. + // + std::unordered_map parameters; + + // + // The body of the request. + // + artifact_content_struct body; + + // + // Key/value pairs that provide additional information about the request. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const web_request_struct &); +void from_json(const nlohmann::json &, web_request_struct &); + +// +// Describes the response to an HTTP request. +// +struct web_response_struct { + // + // The index within the run.webResponses array of the response object associated with this result. + // + int64_t index; + + // + // The response protocol. Example: 'http'. + // + std::string protocol; + + // + // The response version. Example: '1.1'. + // + std::string version; + + // + // The response status code. Example: 451. + // + int64_t statusCode; + + // + // The response reason. Example: 'Not found'. + // + std::string reasonPhrase; + + // + // The response headers. + // + std::unordered_map headers; + + // + // The body of the response. + // + artifact_content_struct body; + + // + // Specifies whether a response was received from the server. + // + bool noResponseReceived; + + // + // Key/value pairs that provide additional information about the response. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const web_response_struct &); +void from_json(const nlohmann::json &, web_response_struct &); + +// +// A result produced by an analysis tool. +// +struct result_struct { + // + // The stable, unique identifier of the rule, if any, to which this notification is relevant. This member can be used to retrieve rule metadata from the rules dictionary, if it exists. + // + std::string ruleId; + + // + // The index within the tool component rules array of the rule object associated with this result. + // + int64_t ruleIndex; + + // + // A reference used to locate the rule descriptor relevant to this result. + // + reporting_descriptor_reference_struct rule; + + // + // A value that categorizes results by evaluation state. + // + kind_enum kind; + + // + // A value specifying the severity level of the result. + // + level_enum level; + + // + // A message that describes the result. The first sentence of the message only will be displayed when visible space is limited. + // + message_struct message; + + // + // Identifies the artifact that the analysis tool was instructed to scan. This need not be the same as the artifact where the result actually occurred. + // + artifact_location_struct analysisTarget; + + // + // The set of locations where the result was detected. Specify only one location unless the problem indicated by the result can only be corrected by making a change at every specified location. + // + std::vector locations; + + // + // A stable, unique identifer for the result in the form of a GUID. + // + std::string guid; + + // + // A stable, unique identifier for the equivalence class of logically identical results to which this result belongs, in the form of a GUID. + // + std::string correlationGuid; + + // + // A positive integer specifying the number of times this logically unique result was observed in this run. + // + int64_t occurrenceCount; + + // + // A set of strings that contribute to the stable, unique identity of the result. + // + std::unordered_map partialFingerprints; + + // + // A set of strings each of which individually defines a stable, unique identity for the result. + // + std::unordered_map fingerprints; + + // + // An array of 'stack' objects relevant to the result. + // + std::vector stacks; + + // + // An array of 'codeFlow' objects relevant to the result. + // + std::vector codeFlows; + + // + // An array of zero or more unique graph objects associated with the result. + // + std::vector graphs; + + // + // An array of one or more unique 'graphTraversal' objects. + // + std::vector graphTraversals; + + // + // A set of locations relevant to this result. + // + std::vector relatedLocations; + + // + // A set of suppressions relevant to this result. + // + std::vector suppressions; + + // + // The state of a result relative to a baseline of a previous run. + // + baseline_state_enum baselineState; + + // + // A number representing the priority or importance of the result. + // + double rank; + + // + // A set of artifacts relevant to the result. + // + std::vector attachments; + + // + // An absolute URI at which the result can be viewed. + // + std::string hostedViewerUri; + + // + // The URIs of the work items associated with this result. + // + std::vector workItemUris; + + // + // Information about how and when the result was detected. + // + result_provenance_struct provenance; + + // + // An array of 'fix' objects, each of which represents a proposed fix to the problem indicated by the result. + // + std::vector fixes; + + // + // An array of references to taxonomy reporting descriptors that are applicable to the result. + // + std::vector taxa; + + // + // A web request associated with this result. + // + web_request_struct webRequest; + + // + // A web response associated with this result. + // + web_response_struct webResponse; + + // + // Key/value pairs that provide additional information about the result. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const result_struct &); +void from_json(const nlohmann::json &, result_struct &); +struct version_control_details_struct; + +// +// Information that describes a run's identity and role within an engineering system process. +// +struct run_automation_details_struct { + // + // A description of the identity and role played within the engineering system by this object's containing run object. + // + message_struct description; + + // + // A hierarchical string that uniquely identifies this object's containing run object. + // + std::string id; + + // + // A stable, unique identifer for this object's containing run object in the form of a GUID. + // + std::string guid; + + // + // A stable, unique identifier for the equivalence class of runs to which this object's containing run object belongs in the form of a GUID. + // + std::string correlationGuid; + + // + // Key/value pairs that provide additional information about the run automation details. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const run_automation_details_struct &); +void from_json(const nlohmann::json &, run_automation_details_struct &); + +enum class column_kind_enum { + kUtf16CodeUnits, + kUnicodeCodePoints, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(column_kind_enum, { + {column_kind_enum::kUtf16CodeUnits, "utf16CodeUnits"}, + {column_kind_enum::kUnicodeCodePoints, "unicodeCodePoints"}, +}) + +// +// Defines locations of special significance to SARIF consumers. +// +struct special_locations_struct { + // + // Provides a suggestion to SARIF consumers to display file paths relative to the specified location. + // + artifact_location_struct displayBase; + + // + // Key/value pairs that provide additional information about the special locations. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const special_locations_struct &); +void from_json(const nlohmann::json &, special_locations_struct &); + +// +// Describes a single run of an analysis tool, and contains the reported output of that run. +// +struct run_struct { + // + // Information about the tool or tool pipeline that generated the results in this run. A run can only contain results produced by a single tool or tool pipeline. A run can aggregate results from multiple log files, as long as context around the tool run (tool command-line arguments and the like) is identical for all aggregated files. + // + tool_struct tool; + + // + // Describes the invocation of the analysis tool. + // + std::vector invocations; + + // + // A conversion object that describes how a converter transformed an analysis tool's native reporting format into the SARIF format. + // + conversion_struct conversion; + + // + // The language of the messages emitted into the log file during this run (expressed as an ISO 639-1 two-letter lowercase culture code) and an optional region (expressed as an ISO 3166-1 two-letter uppercase subculture code associated with a country or region). The casing is recommended but not required (in order for this data to conform to RFC5646). + // + std::string language; + + // + // Specifies the revision in version control of the artifacts that were scanned. + // + std::vector versionControlProvenance; + + // + // The artifact location specified by each uriBaseId symbol on the machine where the tool originally ran. + // + std::unordered_map originalUriBaseIds; + + // + // An array of artifact objects relevant to the run. + // + std::vector artifacts; + + // + // An array of logical locations such as namespaces, types or functions. + // + std::vector logicalLocations; + + // + // An array of zero or more unique graph objects associated with the run. + // + std::vector graphs; + + // + // The set of results contained in an SARIF log. The results array can be omitted when a run is solely exporting rules metadata. It must be present (but may be empty) if a log file represents an actual scan. + // + std::vector results; + + // + // Automation details that describe this run. + // + run_automation_details_struct automationDetails; + + // + // Automation details that describe the aggregate of runs to which this run belongs. + // + std::vector runAggregates; + + // + // The 'guid' property of a previous SARIF 'run' that comprises the baseline that was used to compute result 'baselineState' properties for the run. + // + std::string baselineGuid; + + // + // An array of strings used to replace sensitive information in a redaction-aware property. + // + std::vector redactionTokens; + + // + // Specifies the default encoding for any artifact object that refers to a text file. + // + std::string defaultEncoding; + + // + // Specifies the default source language for any artifact object that refers to a text file that contains source code. + // + std::string defaultSourceLanguage; + + // + // An ordered list of character sequences that were treated as line breaks when computing region information for the run. + // + std::vector newlineSequences; + + // + // Specifies the unit in which the tool measures columns. + // + column_kind_enum columnKind; + + // + // References to external property files that should be inlined with the content of a root log file. + // + external_property_file_references_struct externalPropertyFileReferences; + + // + // An array of threadFlowLocation objects cached at run level. + // + std::vector threadFlowLocations; + + // + // An array of toolComponent objects relevant to a taxonomy in which results are categorized. + // + std::vector taxonomies; + + // + // Addresses associated with this run instance, if any. + // + std::vector addresses; + + // + // The set of available translations of the localized data provided by the tool. + // + std::vector translations; + + // + // Contains configurations that may potentially override both reportingDescriptor.defaultConfiguration (the tool's default severities) and invocation.configurationOverrides (severities established at run-time from the command line). + // + std::vector policies; + + // + // An array of request objects cached at run level. + // + std::vector webRequests; + + // + // An array of response objects cached at run level. + // + std::vector webResponses; + + // + // A specialLocations object that defines locations of special significance to SARIF consumers. + // + special_locations_struct specialLocations; + + // + // Key/value pairs that provide additional information about the run. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const run_struct &); +void from_json(const nlohmann::json &, run_struct &); + +// +// A function call within a stack trace. +// +struct stack_frame_struct { + // + // The location to which this stack frame refers. + // + location_struct location; + + // + // The name of the module that contains the code of this stack frame. + // + std::string module; + + // + // The thread identifier of the stack frame. + // + int64_t threadId; + + // + // The parameters of the call that is executing. + // + std::vector parameters; + + // + // Key/value pairs that provide additional information about the stack frame. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const stack_frame_struct &); +void from_json(const nlohmann::json &, stack_frame_struct &); + +enum class state_enum { + kAccepted, + kUnderReview, + kRejected, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(state_enum, { + {state_enum::kAccepted, "accepted"}, + {state_enum::kUnderReview, "underReview"}, + {state_enum::kRejected, "rejected"}, +}) + +// +// A suppression that is relevant to a result. +// +struct suppression_struct { + // + // A stable, unique identifer for the suprression in the form of a GUID. + // + std::string guid; + + // + // A string that indicates where the suppression is persisted. + // + kind_enum kind; + + // + // A string that indicates the state of the suppression. + // + state_enum state; + + // + // A string representing the justification for the suppression. + // + std::string justification; + + // + // Identifies the location associated with the suppression. + // + location_struct location; + + // + // Key/value pairs that provide additional information about the suppression. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const suppression_struct &); +void from_json(const nlohmann::json &, suppression_struct &); + +// +// Describes a sequence of code locations that specify a path through a single thread of execution such as an operating system or fiber. +// +struct thread_flow_struct { + // + // An string that uniquely identifies the threadFlow within the codeFlow in which it occurs. + // + std::string id; + + // + // A message relevant to the thread flow. + // + message_struct message; + + // + // Values of relevant expressions at the start of the thread flow that may change during thread flow execution. + // + std::unordered_map initialState; + + // + // Values of relevant expressions at the start of the thread flow that remain constant. + // + std::unordered_map immutableState; + + // + // A temporally ordered array of 'threadFlowLocation' objects, each of which describes a location visited by the tool while producing the result. + // + std::vector locations; + + // + // Key/value pairs that provide additional information about the thread flow. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const thread_flow_struct &); +void from_json(const nlohmann::json &, thread_flow_struct &); + +enum class importance_enum { + kImportant, + kEssential, + kUnimportant, +}; + +NLOHMANN_JSON_SERIALIZE_ENUM(importance_enum, { + {importance_enum::kImportant, "important"}, + {importance_enum::kEssential, "essential"}, + {importance_enum::kUnimportant, "unimportant"}, +}) + +// +// A location visited by an analysis tool while simulating or monitoring the execution of a program. +// +struct thread_flow_location_struct { + // + // The index within the run threadFlowLocations array. + // + int64_t index; + + // + // The code location. + // + location_struct location; + + // + // The call stack leading to this location. + // + stack_struct stack; + + // + // A set of distinct strings that categorize the thread flow location. Well-known kinds include 'acquire', 'release', 'enter', 'exit', 'call', 'return', 'branch', 'implicit', 'false', 'true', 'caution', 'danger', 'unknown', 'unreachable', 'taint', 'function', 'handler', 'lock', 'memory', 'resource', 'scope' and 'value'. + // + std::vector kinds; + + // + // An array of references to rule or taxonomy reporting descriptors that are applicable to the thread flow location. + // + std::vector taxa; + + // + // The name of the module that contains the code that is executing. + // + std::string module; + + // + // A dictionary, each of whose keys specifies a variable or expression, the associated value of which represents the variable or expression value. For an annotation of kind 'continuation', for example, this dictionary might hold the current assumed values of a set of global variables. + // + std::unordered_map state; + + // + // An integer representing a containment hierarchy within the thread flow. + // + int64_t nestingLevel; + + // + // An integer representing the temporal order in which execution reached this location. + // + int64_t executionOrder; + + // + // The Coordinated Universal Time (UTC) date and time at which this location was executed. + // + std::string executionTimeUtc; + + // + // Specifies the importance of this location in understanding the code flow in which it occurs. The order from most to least important is "essential", "important", "unimportant". Default: "important". + // + importance_enum importance; + + // + // A web request associated with this thread flow location. + // + web_request_struct webRequest; + + // + // A web response associated with this thread flow location. + // + web_response_struct webResponse; + + // + // Key/value pairs that provide additional information about the threadflow location. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const thread_flow_location_struct &); +void from_json(const nlohmann::json &, thread_flow_location_struct &); + +// +// Specifies the information necessary to retrieve a desired revision from a version control system. +// +struct version_control_details_struct { + // + // The absolute URI of the repository. + // + std::string repositoryUri; + + // + // A string that uniquely and permanently identifies the revision within the repository. + // + std::string revisionId; + + // + // The name of a branch containing the revision. + // + std::string branch; + + // + // A tag that has been applied to the revision. + // + std::string revisionTag; + + // + // A Coordinated Universal Time (UTC) date and time that can be used to synchronize an enlistment to the state of the repository at that time. + // + std::string asOfTimeUtc; + + // + // The location in the local file system to which the root of the repository was mapped at the time of the analysis. + // + artifact_location_struct mappedTo; + + // + // Key/value pairs that provide additional information about the version control details. + // + property_bag_struct properties; +}; + +void to_json(nlohmann::json &, const version_control_details_struct &); +void from_json(const nlohmann::json &, version_control_details_struct &); + +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(property_bag_struct, tags) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(root_struct, version, runs, inlineExternalProperties, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(address_struct, absoluteAddress, relativeAddress, length, kind, name, fullyQualifiedName, offsetFromParent, index, parentIndex, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(message_struct, text, markdown, id, arguments, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(artifact_location_struct, uri, uriBaseId, index, description, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(multiformat_message_string_struct, text, markdown, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(artifact_content_struct, text, binary, rendered, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(artifact_struct, description, location, parentIndex, offset, length, roles, mimeType, contents, encoding, sourceLanguage, hashes, lastModifiedTimeUtc, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(artifact_change_struct, artifactLocation, replacements, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(attachment_struct, description, artifactLocation, regions, rectangles, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(code_flow_struct, message, threadFlows, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(reporting_configuration_struct, enabled, level, rank, parameters, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(tool_component_reference_struct, name, index, guid, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(reporting_descriptor_reference_struct, id, index, guid, toolComponent, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(configuration_override_struct, configuration, descriptor, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(translation_metadata_struct, name, fullName, shortDescription, fullDescription, downloadUri, informationUri, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(tool_component_struct, guid, name, organization, product, productSuite, shortDescription, fullDescription, fullName, version, semanticVersion, dottedQuadFileVersion, releaseDateUtc, downloadUri, informationUri, globalMessageStrings, notifications, rules, taxa, locations, language, contents, isComprehensive, localizedDataSemanticVersion, minimumRequiredLocalizedDataSemanticVersion, associatedComponent, translationMetadata, supportedTaxonomies, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(tool_struct, driver, extensions, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(invocation_struct, commandLine, arguments, responseFiles, startTimeUtc, endTimeUtc, exitCode, ruleConfigurationOverrides, notificationConfigurationOverrides, toolExecutionNotifications, toolConfigurationNotifications, exitCodeDescription, exitSignalName, exitSignalNumber, processStartFailureMessage, executionSuccessful, machine, account, processId, executableLocation, workingDirectory, environmentVariables, stdin, stdout, stderr, stdoutStderr, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(conversion_struct, tool, invocation, analysisToolLogFiles, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(edge_struct, id, label, sourceNodeId, targetNodeId, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(edge_traversal_struct, edgeId, message, finalState, stepOverEdgeCount, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(stack_struct, message, frames, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(exception_struct, kind, message, stack, innerExceptions, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(external_properties_struct, schema, version, guid, runGuid, conversion, graphs, externalizedProperties, artifacts, invocations, logicalLocations, threadFlowLocations, results, taxonomies, driver, extensions, policies, translations, addresses, webRequests, webResponses, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(external_property_file_reference_struct, location, guid, itemCount, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(external_property_file_references_struct, conversion, graphs, externalizedProperties, artifacts, invocations, logicalLocations, threadFlowLocations, results, taxonomies, addresses, driver, extensions, policies, translations, webRequests, webResponses, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(fix_struct, description, artifactChanges, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(graph_struct, description, nodes, edges, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(graph_traversal_struct, runGraphIndex, resultGraphIndex, description, initialState, immutableState, edgeTraversals, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(region_struct, startLine, startColumn, endLine, endColumn, charOffset, charLength, byteOffset, byteLength, snippet, message, sourceLanguage, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(physical_location_struct, address, artifactLocation, region, contextRegion, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(location_struct, id, physicalLocation, logicalLocations, message, annotations, relationships, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(location_relationship_struct, target, kinds, description, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(logical_location_struct, name, index, fullyQualifiedName, decoratedName, parentIndex, kind, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(node_struct, id, label, location, children, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(notification_struct, locations, message, level, threadId, timeUtc, exception, descriptor, associatedRule, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(rectangle_struct, top, left, bottom, right, message, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(replacement_struct, deletedRegion, insertedContent, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(reporting_descriptor_struct, id, deprecatedIds, guid, deprecatedGuids, name, deprecatedNames, shortDescription, fullDescription, messageStrings, defaultConfiguration, helpUri, help, relationships, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(reporting_descriptor_relationship_struct, target, kinds, description, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(result_provenance_struct, firstDetectionTimeUtc, lastDetectionTimeUtc, firstDetectionRunGuid, lastDetectionRunGuid, invocationIndex, conversionSources, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(web_request_struct, index, protocol, version, target, method, headers, parameters, body, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(web_response_struct, index, protocol, version, statusCode, reasonPhrase, headers, body, noResponseReceived, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(result_struct, ruleId, ruleIndex, rule, kind, level, message, analysisTarget, locations, guid, correlationGuid, occurrenceCount, partialFingerprints, fingerprints, stacks, codeFlows, graphs, graphTraversals, relatedLocations, suppressions, baselineState, rank, attachments, hostedViewerUri, workItemUris, provenance, fixes, taxa, webRequest, webResponse, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(run_automation_details_struct, description, id, guid, correlationGuid, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(special_locations_struct, displayBase, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(run_struct, tool, invocations, conversion, language, versionControlProvenance, originalUriBaseIds, artifacts, logicalLocations, graphs, results, automationDetails, runAggregates, baselineGuid, redactionTokens, defaultEncoding, defaultSourceLanguage, newlineSequences, columnKind, externalPropertyFileReferences, threadFlowLocations, taxonomies, addresses, translations, policies, webRequests, webResponses, specialLocations, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(stack_frame_struct, location, module, threadId, parameters, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(suppression_struct, guid, kind, state, justification, location, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(thread_flow_struct, id, message, initialState, immutableState, locations, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(thread_flow_location_struct, index, location, stack, kinds, taxa, module, state, nestingLevel, executionOrder, executionTimeUtc, importance, webRequest, webResponse, properties) +NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(version_control_details_struct, repositoryUri, revisionId, branch, revisionTag, asOfTimeUtc, mappedTo, properties) +} // namespace gap::sarif::definitions \ No newline at end of file diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 4c3aebe..ed69d20 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -34,6 +34,7 @@ endfunction() add_subdirectory(core) add_subdirectory(coro) add_subdirectory(graph) +add_subdirectory(sarif) if (${GAP_ENABLE_MLIR}) add_subdirectory(mlir) diff --git a/test/sarif/CMakeLists.txt b/test/sarif/CMakeLists.txt new file mode 100644 index 0000000..fe0b48c --- /dev/null +++ b/test/sarif/CMakeLists.txt @@ -0,0 +1,10 @@ +# Copyright 2024, Trail of Bits, Inc. All rights reserved. + +add_gap_test(test-gap-sarif + sarif.cpp +) + +target_link_libraries(test-gap-sarif + PUBLIC + gap-sarif +) \ No newline at end of file diff --git a/test/sarif/sarif.cpp b/test/sarif/sarif.cpp new file mode 100644 index 0000000..049842a --- /dev/null +++ b/test/sarif/sarif.cpp @@ -0,0 +1,8 @@ +// Copyright (c) 2024-present, Trail of Bits, Inc. + +#include +#include +#include +#include + +namespace gap::sarif {} \ No newline at end of file diff --git a/vcpkg.json b/vcpkg.json index 18336ac..9777497 100644 --- a/vcpkg.json +++ b/vcpkg.json @@ -2,7 +2,8 @@ "name": "main", "version-string": "latest", "dependencies": [ - "spdlog" + "spdlog", + "nlohmann-json" ], "features": { "with-doctest": {