From 7f33c7048cc3544859471f8c0e97830b1e3c93c3 Mon Sep 17 00:00:00 2001 From: Laurent Laville Date: Wed, 4 Dec 2024 05:37:17 +0000 Subject: [PATCH] keep an up-to-date documentation and avoid outdated copies of sarif and php scripts --- .gitignore | 1 + docs/assets/sarif/.gitkeep | 0 docs/assets/sarif/message/.gitkeep | 0 docs/reference/address.md | 98 +---- docs/reference/artifact.md | 94 +---- docs/reference/artifactChange.md | 92 +---- docs/reference/artifactContent.md | 92 +---- docs/reference/attachment.md | 78 +--- docs/reference/codeFlow.md | 135 +------ docs/reference/configurationOverride.md | 102 +----- docs/reference/conversion.md | 84 +---- docs/reference/edge.md | 116 +----- docs/reference/edgeTraversal.md | 184 +--------- docs/reference/exception.md | 116 +----- docs/reference/externalProperties.md | 105 +----- .../externalPropertyFileReference.md | 114 +----- .../externalPropertyFileReferences.md | 114 +----- docs/reference/fix.md | 101 +---- docs/reference/graph.md | 104 +----- docs/reference/graphTraversal.md | 184 +--------- docs/reference/invocation.md | 109 +----- docs/reference/locationRelationship.md | 177 +-------- docs/reference/logicalLocation.md | 76 +--- docs/reference/message.md | 344 +++++------------- docs/reference/node.md | 104 +----- docs/reference/notification.md | 98 +---- docs/reference/physicalLocation.md | 86 +---- docs/reference/rectangle.md | 95 +---- docs/reference/replacement.md | 92 +---- docs/reference/reportingConfiguration.md | 79 +--- docs/reference/reportingDescriptor.md | 98 +---- .../reference/reportingDescriptorReference.md | 98 +---- .../reportingDescriptorRelationship.md | 86 +---- docs/reference/result.md | 103 +----- docs/reference/resultProvenance.md | 99 +---- docs/reference/run.md | 78 ++-- docs/reference/runAutomationDetails.md | 90 +---- docs/reference/sarifLog.md | 41 +-- docs/reference/specialLocations.md | 94 +---- docs/reference/stack.md | 137 +------ docs/reference/stackFrame.md | 137 +------ docs/reference/suppression.md | 74 +--- docs/reference/threadFlow.md | 127 +------ docs/reference/threadFlowLocation.md | 121 +----- docs/reference/tool.md | 81 ++--- docs/reference/toolComponentReference.md | 84 +---- docs/reference/translationMetadata.md | 79 +--- docs/reference/versionControlDetails.md | 103 +----- docs/reference/webRequest.md | 97 +---- docs/reference/webResponse.md | 103 +----- mkdocs.yml | 26 +- resources/gh-pages-hook.sh | 41 +++ 52 files changed, 1050 insertions(+), 4121 deletions(-) create mode 100644 docs/assets/sarif/.gitkeep create mode 100644 docs/assets/sarif/message/.gitkeep diff --git a/.gitignore b/.gitignore index 4fe8d4c..0d2ab8b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ ###################################### docs/assets/images/ +docs/assets/sarif/ site/ ###### Composer dependencies ###### diff --git a/docs/assets/sarif/.gitkeep b/docs/assets/sarif/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/assets/sarif/message/.gitkeep b/docs/assets/sarif/message/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/reference/address.md b/docs/reference/address.md index 7e1b62d..4a3e21e 100644 --- a/docs/reference/address.md +++ b/docs/reference/address.md @@ -4,91 +4,31 @@ An `address` object describes a physical or virtual address, or a range of addresses, in an “addressable region” (memory or a binary file). -![address object](../assets/images/reference-address.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![address object](../assets/images/reference-address.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "addresses": [ - { - "absoluteAddress": 1024, - "kind": "module", - "name": "Multitool.exe" - }, - { - "absoluteAddress": 1400, - "relativeAddress": 376, - "kind": "header", - "name": "Sections", - "offsetFromParent": 376, - "parentIndex": 0 - }, - { - "absoluteAddress": 1536, - "relativeAddress": 512, - "kind": "section", - "name": ".text", - "offsetFromParent": 136, - "parentIndex": 1 - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php address docs/assets/sarif 192` -See full [`examples/address.php`][example-script] script into repository. + ```json title="docs/assets/sarif/address.json" + --8<-- "docs/assets/sarif/address.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/address.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/address.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/address.php + ```php title="examples/address.php" + --8<-- "examples/address.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$address1 = new Address(); -$address1->setName('Multitool.exe'); -$address1->setKind('module'); -$address1->setAbsoluteAddress(1024); - -$address2 = new Address(); -$address2->setName('Sections'); -$address2->setKind('header'); -$address2->setParentIndex(0); -$address2->setOffsetFromParent(376); -$address2->setAbsoluteAddress(1400); -$address2->setRelativeAddress(376); - -$address3 = new Address(); -$address3->setName('.text'); -$address3->setKind('section'); -$address3->setParentIndex(1); -$address3->setOffsetFromParent(136); -$address3->setAbsoluteAddress(1536); -$address3->setRelativeAddress(512); - -$run = new Run($tool); -$run->addAddresses([$address1, $address2, $address3]); - -``` + ```php title="examples/builder/address.php" + --8<-- "examples/builder/address.php" + ``` diff --git a/docs/reference/artifact.md b/docs/reference/artifact.md index 0079956..fd24f17 100644 --- a/docs/reference/artifact.md +++ b/docs/reference/artifact.md @@ -3,87 +3,31 @@ An `artifact` object represents a single artifact. -![artifact object](../assets/images/reference-artifact.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![artifact object](../assets/images/reference-artifact.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "artifacts": [ - { - "location": { - "uri": "file:///C:/Code/app.zip" - }, - "mimeType": "application/zip" - }, - { - "location": { - "uri": "docs/intro.docx" - }, - "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document" - }, - { - "parentIndex": 1, - "offset": 17522, - "length": 4050, - "mimeType": "application/x-contoso-animation" - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php artifact docs/assets/sarif 192` -See full [`examples/artifact.php`][example-script] script into repository. + ```json title="docs/assets/sarif/artifact.json" + --8<-- "docs/assets/sarif/artifact.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/artifact.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/artifact.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/artifact.php + ```php title="examples/artifact.php" + --8<-- "examples/artifact.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$artifact1 = new Artifact(); -$artifactLocation1 = new ArtifactLocation(); -$artifactLocation1->setUri('file:///C:/Code/app.zip'); -$artifact1->setLocation($artifactLocation1); -$artifact1->setMimeType('application/zip'); - -$artifact2 = new Artifact(); -$artifactLocation2 = new ArtifactLocation(); -$artifactLocation2->setUri('docs/intro.docx'); -$artifact2->setLocation($artifactLocation2); -$artifact2->setMimeType('application/vnd.openxmlformats-officedocument.wordprocessingml.document'); -$artifact2->setParentIndex(0); - -$artifact3 = new Artifact(); -$artifact3->setOffset(17522); -$artifact3->setLength(4050); -$artifact3->setMimeType('application/x-contoso-animation'); -$artifact3->setParentIndex(1); - -$run = new Run($tool); -$run->addArtifacts([$artifact1, $artifact2, $artifact3]); - -``` + ```php title="examples/builder/artifact.php" + --8<-- "examples/builder/artifact.php" + ``` diff --git a/docs/reference/artifactChange.md b/docs/reference/artifactChange.md index ddf4185..6d9b9fa 100644 --- a/docs/reference/artifactChange.md +++ b/docs/reference/artifactChange.md @@ -3,85 +3,31 @@ An `artifactChange` object represents a change to a single artifact. -![artifactChange object](../assets/images/reference-artifact-change.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![artifactChange object](../assets/images/reference-artifact-change.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CA1001", - "fixes": [ - { - "artifactChanges": [ - { - "artifactLocation": { - "uri": "src/a.c" - }, - "replacements": [ - { - "deletedRegion": { - "startLine": 1, - "startColumn": 1, - "endLine": 1 - }, - "insertedContent": { - "text": "// " - } - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php fix docs/assets/sarif 192` -See full [`examples/fix.php`][example-script] script into repository. + ```json title="docs/assets/sarif/fix.json" + --8<-- "docs/assets/sarif/fix.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/fix.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/fix.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/fix.php + ```php title="examples/fix.php" + --8<-- "examples/fix.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('src/a.c'); -$replacement = new Replacement(new Region(1, 1, 1)); -$insertedContent = new ArtifactContent(); -$insertedContent->setText('// '); -$replacement->setInsertedContent($insertedContent); -$artifactChange = new ArtifactChange($artifactLocation, [$replacement]); - -``` + ```php title="examples/builder/fix.php" + --8<-- "examples/builder/fix.php" + ``` diff --git a/docs/reference/artifactContent.md b/docs/reference/artifactContent.md index 7d1379b..ad84f4b 100644 --- a/docs/reference/artifactContent.md +++ b/docs/reference/artifactContent.md @@ -5,85 +5,31 @@ Certain properties in this document represent the contents of portions of artifa for example, artifacts that were scanned by an analysis tool. SARIF represents such content with an `artifactContent` object. Depending on the circumstances, the SARIF log file might need to represent this content as readable text, raw bytes, or both. -![artifactContent object](../assets/images/reference-artifact-content.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![artifactContent object](../assets/images/reference-artifact-content.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CA1001", - "fixes": [ - { - "artifactChanges": [ - { - "artifactLocation": { - "uri": "src/a.c" - }, - "replacements": [ - { - "deletedRegion": { - "startLine": 1, - "startColumn": 1, - "endLine": 1 - }, - "insertedContent": { - "text": "// " - } - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php fix docs/assets/sarif 192` -See full [`examples/fix.php`][example-script] script into repository. + ```json title="docs/assets/sarif/fix.json" + --8<-- "docs/assets/sarif/fix.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/fix.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/fix.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/fix.php + ```php title="examples/fix.php" + --8<-- "examples/fix.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('src/a.c'); -$replacement = new Replacement(new Region(1, 1, 1)); -$insertedContent = new ArtifactContent(); -$insertedContent->setText('// '); -$replacement->setInsertedContent($insertedContent); -$artifactChange = new ArtifactChange($artifactLocation, [$replacement]); - -``` + ```php title="examples/builder/fix.php" + --8<-- "examples/builder/fix.php" + ``` diff --git a/docs/reference/attachment.md b/docs/reference/attachment.md index d724eab..f881e9a 100644 --- a/docs/reference/attachment.md +++ b/docs/reference/attachment.md @@ -3,71 +3,31 @@ An `attachment` object describes an artifact relevant to the detection of a result. -![attachment object](../assets/images/reference-attachment.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![attachment object](../assets/images/reference-attachment.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Have a look on screen shot provided" - }, - "attachments": [ - { - "artifactLocation": { - "uri": "file:///C:/ScanOutput/image001.png" - }, - "description": { - "text": "Screen shot" - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php attachment docs/assets/sarif 192` -See full [`examples/attachment.php`][example-script] script into repository. + ```json title="docs/assets/sarif/attachment.json" + --8<-- "docs/assets/sarif/attachment.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/attachment.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/attachment.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/attachment.php + ```php title="examples/attachment.php" + --8<-- "examples/attachment.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$attachment = new Attachment(); -$attachment->setDescription(new Message('Screen shot')); -$attachment->setArtifactLocation(new ArtifactLocation('file:///C:/ScanOutput/image001.png')); - -$result = new Result(new Message('Have a look on screen shot provided')); -$result->addAttachments([$attachment]); - -``` + ```php title="examples/builder/attachment.php" + --8<-- "examples/builder/attachment.php" + ``` diff --git a/docs/reference/codeFlow.md b/docs/reference/codeFlow.md index 101cb7b..c6e578c 100644 --- a/docs/reference/codeFlow.md +++ b/docs/reference/codeFlow.md @@ -4,128 +4,31 @@ A `codeFlow` object describes the progress of one or more programs through one or more thread flows, which together lead to the detection of a problem in the system being analyzed. -![codeFlow object](../assets/images/reference-code-flow.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![codeFlow object](../assets/images/reference-code-flow.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "A result object" - }, - "codeFlows": [ - { - "threadFlows": [ - { - "locations": [ - { - "location": { - "physicalLocation": { - "artifactLocation": { - "uri": "ui/window.c", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 42 - } - } - }, - "state": { - "x": { - "text": "42" - }, - "y": { - "text": "54" - }, - "x+y": { - "text": "96" - } - }, - "nestingLevel": 0, - "executionOrder": 2 - } - ], - "id": "thread-123", - "message": { - "text": "A threadFlow object" - } - } - ], - "message": { - "text": "A codeFlow object" - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php codeFlow docs/assets/sarif 192` -See full [`examples/codeFlow.php`][example-script] script into repository. + ```json title="docs/assets/sarif/codeFlow.json" + --8<-- "docs/assets/sarif/codeFlow.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/codeFlow.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/codeFlow.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/codeFlow.php + ```php title="examples/codeFlow.php" + --8<-- "examples/codeFlow.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$threadFlowLocation = new ThreadFlowLocation(); -$location = new Location(); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('ui/window.c'); -$artifactLocation->setUriBaseId('SRCROOT'); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(42)); -$location->setPhysicalLocation($physicalLocation); -$threadFlowLocation->setLocation($location); -$threadFlowLocation->addAdditionalProperties([ - 'x' => new MultiformatMessageString('42'), - 'y' => new MultiformatMessageString('54'), - 'x+y' => new MultiformatMessageString('96'), -]); -$threadFlowLocation->setNestingLevel(0); -$threadFlowLocation->setExecutionOrder(2); - -$threadFlow = new ThreadFlow([$threadFlowLocation]); -$threadFlow->setId('thread-123'); -$threadFlow->setMessage(new Message('A threadFlow object')); - -$codeFlow = new CodeFlow([$threadFlow]); -$codeFlow->setMessage(new Message('A codeFlow object')); - -$result = new Result(new Message('A result object')); -$result->addCodeFlows([$codeFlow]); - -``` + ```php title="examples/builder/codeFlow.php" + --8<-- "examples/builder/codeFlow.php" + ``` diff --git a/docs/reference/configurationOverride.md b/docs/reference/configurationOverride.md index ece66ff..dd4c228 100644 --- a/docs/reference/configurationOverride.md +++ b/docs/reference/configurationOverride.md @@ -4,95 +4,31 @@ A `configurationOverride` object modifies the effective runtime configuration of a specified `reportingDescriptor` object, which we refer to as theDescriptor. -![configurationOverride object](../assets/images/reference-configuration-override.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![configurationOverride object](../assets/images/reference-configuration-override.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CA2101", - "defaultConfiguration": { - "enabled": true, - "level": "error", - "rank": -1 - } - } - ] - } - }, - "invocations": [ - { - "executionSuccessful": true, - "ruleConfigurationOverrides": [ - { - "configuration": { - "enabled": true, - "level": "warning", - "rank": -1 - }, - "descriptor": { - "index": 0 - } - } - ] - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php configurationOverride docs/assets/sarif 192` -See full [`examples/configurationOverride.php`][example-script] script into repository. + ```json title="docs/assets/sarif/configurationOverride.json" + --8<-- "docs/assets/sarif/configurationOverride.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/configurationOverride.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/configurationOverride.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/configurationOverride.php + ```php title="examples/configurationOverride.php" + --8<-- "examples/configurationOverride.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$rule = new ReportingDescriptor('CA2101'); -$reportingConf = new ReportingConfiguration(); -$reportingConf->setLevel('error'); -$rule->setDefaultConfiguration($reportingConf); -$driver->addRules([$rule]); - -$ruleConf = new ReportingConfiguration(); -$ruleConf->setLevel('warning'); - -$confOverrides = new ConfigurationOverride(); -$descriptor = new ReportingDescriptorReference(0); -$confOverrides->setDescriptor($descriptor); -$confOverrides->setConfiguration($ruleConf); - -$invocation = new Invocation(true); -$invocation->addRuleConfigurationOverrides([$confOverrides]); - -$run = new Run($tool); -$run->addInvocations([$invocation]); - -``` + ```php title="examples/builder/configurationOverride.php" + --8<-- "examples/builder/configurationOverride.php" + ``` diff --git a/docs/reference/conversion.md b/docs/reference/conversion.md index 3254a34..b058c57 100644 --- a/docs/reference/conversion.md +++ b/docs/reference/conversion.md @@ -4,77 +4,31 @@ A `conversion` object describes how a converter transformed the output of an analysis tool from the analysis tool’s native output format into the SARIF format. -![conversion object](../assets/images/reference-conversion.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![conversion object](../assets/images/reference-conversion.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "AndroidStudio", - "semanticVersion": "1.0.0-beta.1", - "informationUri": "https://android-studion.dev" - } - }, - "conversion": { - "tool": { - "driver": { - "name": "SARIF SDK Multitool" - } - }, - "invocation": { - "executionSuccessful": true, - "commandLine": "Sarif.Multitool.exe convert -t AndroidStudio northwind.log" - }, - "analysisToolLogFiles": [ - { - "uri": "northwind.log", - "uriBaseId": "$LOG_DIR$" - } - ] - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php conversion docs/assets/sarif 192` -See full [`examples/conversion.php`][example-script] script into repository. + ```json title="docs/assets/sarif/conversion.json" + --8<-- "docs/assets/sarif/conversion.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/conversion.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/conversion.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/conversion.php + ```php title="examples/conversion.php" + --8<-- "examples/conversion.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('northwind.log'); -$artifactLocation->setUriBaseId('$LOG_DIR$'); - -$invocation = new Invocation(true); -$invocation->setCommandLine('Sarif.Multitool.exe convert -t AndroidStudio northwind.log'); - -$conversion = new Conversion($converter); -$conversion->addAnalysisToolLogFiles([$artifactLocation]); -$conversion->setInvocation($invocation); - -$run = new Run($tool); -$run->setConversion($conversion); - -``` + ```php title="examples/builder/conversion.php" + --8<-- "examples/builder/conversion.php" + ``` diff --git a/docs/reference/edge.md b/docs/reference/edge.md index ce17c40..170e2d7 100644 --- a/docs/reference/edge.md +++ b/docs/reference/edge.md @@ -3,109 +3,31 @@ A `edge` object represents a directed edge in the graph represented by theGraph. -![edge object](../assets/images/reference-edge.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![edge object](../assets/images/reference-edge.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Have a look on this graph" - }, - "graphs": [ - { - "nodes": [ - { - "id": "n2" - }, - { - "id": "n3" - }, - { - "id": "n4" - }, - { - "id": "n1", - "children": [ - { - "id": "n3" - } - ] - } - ], - "edges": [ - { - "id": "e1", - "sourceNodeId": "n3", - "targetNodeId": "n4" - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php graph docs/assets/sarif 192` -See full [`examples/graph.php`][example-script] script into repository. + ```json title="docs/assets/sarif/graph.json" + --8<-- "docs/assets/sarif/graph.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/graph.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/graph.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/graph.php + ```php title="examples/graph.php" + --8<-- "examples/graph.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$nodes = []; -$nodes[2] = new Node('n2'); -$nodes[3] = new Node('n3'); -$nodes[4] = new Node('n4'); -$nodes[1] = new Node('n1'); -$nodes[1]->addChildren([$nodes[3]]); - -$edges = []; -$edges[1] = new Edge('e1', 'n3', 'n4'); - -$graph = new Graph(); -$graph->addNodes($nodes); -$graph->addEdges($edges); - -$result = new Result(new Message('Have a look on this graph')); -$result->addGraphs([$graph]); - -``` + ```php title="examples/builder/graph.php" + --8<-- "examples/builder/graph.php" + ``` diff --git a/docs/reference/edgeTraversal.md b/docs/reference/edgeTraversal.md index 2f37f54..8394fb4 100644 --- a/docs/reference/edgeTraversal.md +++ b/docs/reference/edgeTraversal.md @@ -3,177 +3,31 @@ An `edgeTraversal` object represents the traversal of a single edge during a graph traversal. -![edgeTraversal object](../assets/images/reference-edge-traversal.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![edgeTraversal object](../assets/images/reference-edge-traversal.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "A graph and edge traversal objects" - }, - "graphs": [ - { - "nodes": [ - { - "id": "n1" - }, - { - "id": "n2" - }, - { - "id": "n3" - }, - { - "id": "n4" - } - ], - "edges": [ - { - "id": "e1", - "sourceNodeId": "n1", - "targetNodeId": "n2" - }, - { - "id": "e2", - "sourceNodeId": "n2", - "targetNodeId": "n3" - }, - { - "id": "e3", - "sourceNodeId": "n2", - "targetNodeId": "n4" - } - ] - } - ], - "graphTraversals": [ - { - "resultGraphIndex": 0, - "initialState": { - "x": { - "text": "1" - }, - "y": { - "text": "2" - }, - "x+y": { - "text": "3" - } - }, - "edgeTraversals": [ - { - "edgeId": "e1", - "finalState": { - "x": { - "text": "4" - }, - "y": { - "text": "2" - }, - "x+y": { - "text": "6" - } - } - }, - { - "edgeId": "e3", - "finalState": { - "x": { - "text": "4" - }, - "y": { - "text": "7" - }, - "x+y": { - "text": "11" - } - } - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php graphTraversal docs/assets/sarif 192` -See full [`examples/graphTraversal.php`][example-script] script into repository. + ```json title="docs/assets/sarif/graphTraversal.json" + --8<-- "docs/assets/sarif/graphTraversal.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/graphTraversal.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/graphTraversal.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/graphTraversal.php + ```php title="examples/graphTraversal.php" + --8<-- "examples/graphTraversal.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$nodes = []; -$nodes[1] = new Node('n1'); -$nodes[2] = new Node('n2'); -$nodes[3] = new Node('n3'); -$nodes[4] = new Node('n4'); - -$edges = []; -$edges[1] = new Edge('e1', 'n1', 'n2'); -$edges[2] = new Edge('e2', 'n2', 'n3'); -$edges[3] = new Edge('e3', 'n2', 'n4'); - -$graph = new Graph(); -$graph->addNodes($nodes); -$graph->addEdges($edges); - -$graphTraversal = new GraphTraversal(null, 0); -$graphTraversal->addAdditionalPropertiesInitialState([ - 'x' => new MultiformatMessageString('1'), - 'y' => new MultiformatMessageString('2'), - 'x+y' => new MultiformatMessageString('3'), -]); - -$edgeTraversal1 = new EdgeTraversal('e1'); -$edgeTraversal1->addAdditionalProperties([ - 'x' => new MultiformatMessageString('4'), - 'y' => new MultiformatMessageString('2'), - 'x+y' => new MultiformatMessageString('6'), -]); -$edgeTraversal3 = new EdgeTraversal('e3'); -$edgeTraversal3->addAdditionalProperties([ - 'x' => new MultiformatMessageString('4'), - 'y' => new MultiformatMessageString('7'), - 'x+y' => new MultiformatMessageString('11'), -]); -$graphTraversal->addEdgeTraversals([$edgeTraversal1, $edgeTraversal3]); - -$result = new Result(new Message('A graph and edge traversal objects')); -$result->addGraphs([$graph]); -$result->addGraphTraversals([$graphTraversal]); - -``` + ```php title="examples/builder/graphTraversal.php" + --8<-- "examples/builder/graphTraversal.php" + ``` diff --git a/docs/reference/exception.md b/docs/reference/exception.md index bd7add5..b591312 100644 --- a/docs/reference/exception.md +++ b/docs/reference/exception.md @@ -4,109 +4,31 @@ An `exception` object describes a runtime exception encountered during the execution of an analysis tool. This includes signals in POSIX-conforming operating systems. -![exception object](../assets/images/reference-exception.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![exception object](../assets/images/reference-exception.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CTN9999", - "shortDescription": { - "text": "First version of rule." - } - }, - { - "id": "CTN9999", - "shortDescription": { - "text": "Second version of rule." - } - } - ] - } - }, - "invocations": [ - { - "executionSuccessful": true, - "toolExecutionNotifications": [ - { - "message": { - "text": "Exception evaluating rule 'C2001'. Rule configuration is missing." - }, - "level": "error", - "exception": { - "message": "Exception evaluating rule 'C2001'" - }, - "descriptor": { - "index": 1, - "id": "CTN9999" - } - } - ] - } - ], - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CTN9999" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php exception docs/assets/sarif 192` -See full [`examples/exception.php`][example-script] script into repository. + ```json title="docs/assets/sarif/exception.json" + --8<-- "docs/assets/sarif/exception.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/exception.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/exception.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/exception.php + ```php title="examples/exception.php" + --8<-- "examples/exception.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$notification = new Notification(new Message("Exception evaluating rule 'C2001'. Rule configuration is missing.")); -$notification->setAssociatedRule(new ReportingDescriptorReference(0, 'C2001')); -$notification->setDescriptor(new ReportingDescriptorReference(1, 'CTN9999')); -$notification->setLevel('error'); -$exception = new Exception(); -$exception->setMessage("Exception evaluating rule 'C2001'"); -$notification->setRuntimeException($exception); -$invocation = new Invocation(true); -$invocation->addToolExecutionNotifications([$notification]); - -$result = new Result(new Message('...')); -$result->setRuleId('CTN9999'); - -$run = new Run($tool); -$run->addResults([$result]); -$run->addInvocations([$invocation]); - -``` + ```php title="examples/builder/exception.php" + --8<-- "examples/builder/exception.php" + ``` diff --git a/docs/reference/externalProperties.md b/docs/reference/externalProperties.md index 19c59d5..7292a60 100644 --- a/docs/reference/externalProperties.md +++ b/docs/reference/externalProperties.md @@ -3,98 +3,31 @@ The top-level element of an external property file SHALL be an object which we refer to as an `externalProperties` object. -![externalProperties object](../assets/images/reference-external-properties.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![externalProperties object](../assets/images/reference-external-properties.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [] - } - ], - "inlineExternalProperties": [ - { - "schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "guid": "00001111-2222-1111-8888-555566667777", - "runGuid": "88889999-AAAA-1111-8888-DDDDEEEEFFFF", - "externalizedProperties": { - "team": "Security Assurance Team" - }, - "artifacts": [ - { - "location": { - "uri": "apple.png" - }, - "mimeType": "image/png" - }, - { - "location": { - "uri": "banana.png" - }, - "mimeType": "image/png" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php externalProperties docs/assets/sarif 192` -See full [`examples/externalProperties.php`][example-script] script into repository. + ```json title="docs/assets/sarif/externalProperties.json" + --8<-- "docs/assets/sarif/externalProperties.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/externalProperties.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/externalProperties.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/externalProperties.php + ```php title="examples/externalProperties.php" + --8<-- "examples/externalProperties.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$apple = new Artifact(); -$location = new ArtifactLocation(); -$location->setUri('apple.png'); -$apple->setLocation($location); -$apple->setMimeType('image/png'); - -$banana = new Artifact(); -$location = new ArtifactLocation(); -$location->setUri('banana.png'); -$banana->setLocation($location); -$banana->setMimeType('image/png'); - -$propertyBag = new PropertyBag(); -$propertyBag->addProperty('team', 'Security Assurance Team'); - -$run = new Run($tool); - -$log = new SarifLog([$run]); -$externalProperties = new ExternalProperties(); -$externalProperties->setGuid('00001111-2222-1111-8888-555566667777'); -$externalProperties->setRunGuid('88889999-AAAA-1111-8888-DDDDEEEEFFFF'); -$externalProperties->addArtifacts([$apple, $banana]); -$externalProperties->setExternalizedProperties($propertyBag); -$log->addInlineExternalProperties([$externalProperties]); - -``` + ```php title="examples/builder/externalProperties.php" + --8<-- "examples/builder/externalProperties.php" + ``` diff --git a/docs/reference/externalPropertyFileReference.md b/docs/reference/externalPropertyFileReference.md index 24cfbb1..8c5e102 100644 --- a/docs/reference/externalPropertyFileReference.md +++ b/docs/reference/externalPropertyFileReference.md @@ -4,107 +4,31 @@ An `externalPropertyFileReference` object contains information that enables a SARIF consumer to locate the external property files that contain the values of all externalized properties associated with theRun. -![externalPropertyFileReference object](../assets/images/reference-external-property-file-reference.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![externalPropertyFileReference object](../assets/images/reference-external-property-file-reference.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "originalUriBaseIds": { - "LOGSDIR": { - "uri": "file:///C:/logs/" - } - }, - "externalPropertyFileReferences": { - "conversion": { - "location": { - "uri": "scantool.conversion.sarif-external-properties", - "uriBaseId": "LOGSDIR" - }, - "guid": "11111111-1111-1111-8888-111111111111" - }, - "results": [ - { - "location": { - "uri": "scantool.results-1.sarif-external-properties", - "uriBaseId": "LOGSDIR" - }, - "guid": "22222222-2222-1111-8888-222222222222", - "itemCount": 1000 - }, - { - "location": { - "uri": "scantool.results-2.sarif-external-properties", - "uriBaseId": "LOGSDIR" - }, - "guid": "33333333-3333-1111-8888-333333333333", - "itemCount": 4277 - } - ] - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php externalPropertyFileReferences docs/assets/sarif 192` -See full [`examples/externalPropertyFileReferences.php`][example-script] script into repository. + ```json title="docs/assets/sarif/externalPropertyFileReferences.json" + --8<-- "docs/assets/sarif/externalPropertyFileReferences.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/externalPropertyFileReferences.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/externalPropertyFileReferences.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/externalPropertyFileReferences.php + ```php title="examples/externalPropertyFileReferences.php" + --8<-- "examples/externalPropertyFileReferences.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$run = new Run($tool); -$logsDir = new ArtifactLocation(); -$logsDir->setUri('file:///C:/logs/'); -$run->addAdditionalProperties([ - 'LOGSDIR' => $logsDir, -]); - -$location = new ArtifactLocation(); -$location->setUri('scantool.conversion.sarif-external-properties'); -$location->setUriBaseId('LOGSDIR'); -$conversion = new ExternalPropertyFileReference($location, '11111111-1111-1111-8888-111111111111'); - -$location = new ArtifactLocation(); -$location->setUri('scantool.results-1.sarif-external-properties'); -$location->setUriBaseId('LOGSDIR'); -$resultRef1 = new ExternalPropertyFileReference($location, '22222222-2222-1111-8888-222222222222'); -$resultRef1->setItemCount(1000); - -$location = new ArtifactLocation(); -$location->setUri('scantool.results-2.sarif-external-properties'); -$location->setUriBaseId('LOGSDIR'); -$resultRef2 = new ExternalPropertyFileReference($location, '33333333-3333-1111-8888-333333333333'); -$resultRef2->setItemCount(4277); - -$externalPropertyFileReferences = new ExternalPropertyFileReferences(); -$externalPropertyFileReferences->setConversion($conversion); -$externalPropertyFileReferences->addResults([$resultRef1, $resultRef2]); -$run->setExternalPropertyFileReferences($externalPropertyFileReferences); - -``` + ```php title="examples/builder/externalPropertyFileReferences.php" + --8<-- "examples/builder/externalPropertyFileReferences.php" + ``` diff --git a/docs/reference/externalPropertyFileReferences.md b/docs/reference/externalPropertyFileReferences.md index 1dab3b8..7328f0c 100644 --- a/docs/reference/externalPropertyFileReferences.md +++ b/docs/reference/externalPropertyFileReferences.md @@ -4,107 +4,31 @@ An `externalPropertyFileReferences` object contains information that enables a SARIF consumer to locate the external property files that contain the values of all externalized properties associated with theRun. -![externalPropertyFileReferences object](../assets/images/reference-external-property-file-references.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![externalPropertyFileReferences object](../assets/images/reference-external-property-file-references.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "originalUriBaseIds": { - "LOGSDIR": { - "uri": "file:///C:/logs/" - } - }, - "externalPropertyFileReferences": { - "conversion": { - "location": { - "uri": "scantool.conversion.sarif-external-properties", - "uriBaseId": "LOGSDIR" - }, - "guid": "11111111-1111-1111-8888-111111111111" - }, - "results": [ - { - "location": { - "uri": "scantool.results-1.sarif-external-properties", - "uriBaseId": "LOGSDIR" - }, - "guid": "22222222-2222-1111-8888-222222222222", - "itemCount": 1000 - }, - { - "location": { - "uri": "scantool.results-2.sarif-external-properties", - "uriBaseId": "LOGSDIR" - }, - "guid": "33333333-3333-1111-8888-333333333333", - "itemCount": 4277 - } - ] - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php externalPropertyFileReferences docs/assets/sarif 192` -See full [`examples/externalPropertyFileReferences.php`][example-script] script into repository. + ```json title="docs/assets/sarif/externalPropertyFileReferences.json" + --8<-- "docs/assets/sarif/externalPropertyFileReferences.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/externalPropertyFileReferences.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/externalPropertyFileReferences.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/externalPropertyFileReferences.php + ```php title="examples/externalPropertyFileReferences.php" + --8<-- "examples/externalPropertyFileReferences.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$run = new Run($tool); -$logsDir = new ArtifactLocation(); -$logsDir->setUri('file:///C:/logs/'); -$run->addAdditionalProperties([ - 'LOGSDIR' => $logsDir, -]); - -$location = new ArtifactLocation(); -$location->setUri('scantool.conversion.sarif-external-properties'); -$location->setUriBaseId('LOGSDIR'); -$conversion = new ExternalPropertyFileReference($location, '11111111-1111-1111-8888-111111111111'); - -$location = new ArtifactLocation(); -$location->setUri('scantool.results-1.sarif-external-properties'); -$location->setUriBaseId('LOGSDIR'); -$resultRef1 = new ExternalPropertyFileReference($location, '22222222-2222-1111-8888-222222222222'); -$resultRef1->setItemCount(1000); - -$location = new ArtifactLocation(); -$location->setUri('scantool.results-2.sarif-external-properties'); -$location->setUriBaseId('LOGSDIR'); -$resultRef2 = new ExternalPropertyFileReference($location, '33333333-3333-1111-8888-333333333333'); -$resultRef2->setItemCount(4277); - -$externalPropertyFileReferences = new ExternalPropertyFileReferences(); -$externalPropertyFileReferences->setConversion($conversion); -$externalPropertyFileReferences->addResults([$resultRef1, $resultRef2]); -$run->setExternalPropertyFileReferences($externalPropertyFileReferences); - -``` + ```php title="examples/builder/externalPropertyFileReferences.php" + --8<-- "examples/builder/externalPropertyFileReferences.php" + ``` diff --git a/docs/reference/fix.md b/docs/reference/fix.md index 728ee46..ea4b8cf 100644 --- a/docs/reference/fix.md +++ b/docs/reference/fix.md @@ -4,94 +4,31 @@ A `fix` object represents a proposed fix for the problem indicated by theResult. It specifies a set of artifacts to modify. For each artifact, it specifies regions to remove, and provides new content to insert. -![fix object](../assets/images/reference-fix.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![fix object](../assets/images/reference-fix.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CA1001", - "fixes": [ - { - "artifactChanges": [ - { - "artifactLocation": { - "uri": "src/a.c" - }, - "replacements": [ - { - "deletedRegion": { - "startLine": 1, - "startColumn": 1, - "endLine": 1 - }, - "insertedContent": { - "text": "// " - } - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php fix docs/assets/sarif 192` -See full [`examples/fix.php`][example-script] script into repository. + ```json title="docs/assets/sarif/fix.json" + --8<-- "docs/assets/sarif/fix.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/fix.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/fix.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/fix.php + ```php title="examples/fix.php" + --8<-- "examples/fix.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('src/a.c'); -$replacement = new Replacement(new Region(1, 1, 1)); -$insertedContent = new ArtifactContent(); -$insertedContent->setText('// '); -$replacement->setInsertedContent($insertedContent); -$artifactChange = new ArtifactChange($artifactLocation, [$replacement]); - -$fix = new Fix([$artifactChange]); - -$result = new Result(new Message('...')); -$result->setRuleId('CA1001'); -$result->addFixes([$fix]); - -``` + ```php title="examples/builder/fix.php" + --8<-- "examples/builder/fix.php" + ``` diff --git a/docs/reference/graph.md b/docs/reference/graph.md index e1e958c..83405a2 100644 --- a/docs/reference/graph.md +++ b/docs/reference/graph.md @@ -4,97 +4,31 @@ A `graph` object represents a directed graph, a network of nodes and directed edges that describes some aspect of the structure of the code (for example, a call graph). -![graph object](../assets/images/reference-graph.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![graph object](../assets/images/reference-graph.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Have a look on this graph" - }, - "graphs": [ - { - "nodes": [ - { - "id": "n2" - }, - { - "id": "n3" - }, - { - "id": "n4" - }, - { - "id": "n1", - "children": [ - { - "id": "n3" - } - ] - } - ], - "edges": [ - { - "id": "e1", - "sourceNodeId": "n3", - "targetNodeId": "n4" - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php graph docs/assets/sarif 192` -See full [`examples/graph.php`][example-script] script into repository. + ```json title="docs/assets/sarif/graph.json" + --8<-- "docs/assets/sarif/graph.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/graph.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/graph.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/graph.php + ```php title="examples/graph.php" + --8<-- "examples/graph.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$nodes = []; -$nodes[2] = new Node('n2'); -$nodes[3] = new Node('n3'); -$nodes[4] = new Node('n4'); -$nodes[1] = new Node('n1'); -$nodes[1]->addChildren([$nodes[3]]); - -$edges = []; -$edges[1] = new Edge('e1', 'n3', 'n4'); - -$graph = new Graph(); -$graph->addNodes($nodes); -$graph->addEdges($edges); - -``` + ```php title="examples/builder/graph.php" + --8<-- "examples/builder/graph.php" + ``` diff --git a/docs/reference/graphTraversal.md b/docs/reference/graphTraversal.md index 8cf670d..00e1a97 100644 --- a/docs/reference/graphTraversal.md +++ b/docs/reference/graphTraversal.md @@ -4,177 +4,31 @@ A `graphTraversal` object represents a "graph traversal", that is, a path through a graph specified by a sequence of connected "edge traversals", each of which is represented by an `edgeTraversal` object. -![graphTraversal object](../assets/images/reference-graph-traversal.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![graphTraversal object](../assets/images/reference-graph-traversal.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "A graph and edge traversal objects" - }, - "graphs": [ - { - "nodes": [ - { - "id": "n1" - }, - { - "id": "n2" - }, - { - "id": "n3" - }, - { - "id": "n4" - } - ], - "edges": [ - { - "id": "e1", - "sourceNodeId": "n1", - "targetNodeId": "n2" - }, - { - "id": "e2", - "sourceNodeId": "n2", - "targetNodeId": "n3" - }, - { - "id": "e3", - "sourceNodeId": "n2", - "targetNodeId": "n4" - } - ] - } - ], - "graphTraversals": [ - { - "resultGraphIndex": 0, - "initialState": { - "x": { - "text": "1" - }, - "y": { - "text": "2" - }, - "x+y": { - "text": "3" - } - }, - "edgeTraversals": [ - { - "edgeId": "e1", - "finalState": { - "x": { - "text": "4" - }, - "y": { - "text": "2" - }, - "x+y": { - "text": "6" - } - } - }, - { - "edgeId": "e3", - "finalState": { - "x": { - "text": "4" - }, - "y": { - "text": "7" - }, - "x+y": { - "text": "11" - } - } - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php graphTraversal docs/assets/sarif 192` -See full [`examples/graphTraversal.php`][example-script] script into repository. + ```json title="docs/assets/sarif/graphTraversal.json" + --8<-- "docs/assets/sarif/graphTraversal.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/graphTraversal.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/graphTraversal.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/graphTraversal.php + ```php title="examples/graphTraversal.php" + --8<-- "examples/graphTraversal.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$nodes = []; -$nodes[1] = new Node('n1'); -$nodes[2] = new Node('n2'); -$nodes[3] = new Node('n3'); -$nodes[4] = new Node('n4'); - -$edges = []; -$edges[1] = new Edge('e1', 'n1', 'n2'); -$edges[2] = new Edge('e2', 'n2', 'n3'); -$edges[3] = new Edge('e3', 'n2', 'n4'); - -$graph = new Graph(); -$graph->addNodes($nodes); -$graph->addEdges($edges); - -$graphTraversal = new GraphTraversal(null, 0); -$graphTraversal->addAdditionalPropertiesInitialState([ - 'x' => new MultiformatMessageString('1'), - 'y' => new MultiformatMessageString('2'), - 'x+y' => new MultiformatMessageString('3'), -]); - -$edgeTraversal1 = new EdgeTraversal('e1'); -$edgeTraversal1->addAdditionalProperties([ - 'x' => new MultiformatMessageString('4'), - 'y' => new MultiformatMessageString('2'), - 'x+y' => new MultiformatMessageString('6'), -]); -$edgeTraversal3 = new EdgeTraversal('e3'); -$edgeTraversal3->addAdditionalProperties([ - 'x' => new MultiformatMessageString('4'), - 'y' => new MultiformatMessageString('7'), - 'x+y' => new MultiformatMessageString('11'), -]); -$graphTraversal->addEdgeTraversals([$edgeTraversal1, $edgeTraversal3]); - -$result = new Result(new Message('A graph and edge traversal objects')); -$result->addGraphs([$graph]); -$result->addGraphTraversals([$graphTraversal]); - -``` + ```php title="examples/builder/graphTraversal.php" + --8<-- "examples/builder/graphTraversal.php" + ``` diff --git a/docs/reference/invocation.md b/docs/reference/invocation.md index 24eedb4..aa321c2 100644 --- a/docs/reference/invocation.md +++ b/docs/reference/invocation.md @@ -3,102 +3,31 @@ An `invocation` object describes the invocation of the analysis tool that was run. -![invocation object](../assets/images/reference-invocation.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![invocation object](../assets/images/reference-invocation.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CTN9999", - "shortDescription": { - "text": "First version of rule." - } - }, - { - "id": "CTN9999", - "shortDescription": { - "text": "Second version of rule." - } - } - ] - } - }, - "invocations": [ - { - "executionSuccessful": true, - "toolExecutionNotifications": [ - { - "message": { - "text": "Exception evaluating rule 'C2001'. Rule configuration is missing." - }, - "level": "error", - "descriptor": { - "index": 1, - "id": "CTN9999" - } - } - ] - } - ], - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CTN9999" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingDescriptorReference docs/assets/sarif 192` -See full [`examples/reportingDescriptorReference.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingDescriptorReference.json" + --8<-- "docs/assets/sarif/reportingDescriptorReference.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingDescriptorReference.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingDescriptorReference.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingDescriptorReference.php + ```php title="examples/reportingDescriptorReference.php" + --8<-- "examples/reportingDescriptorReference.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$notification = new Notification(new Message("Exception evaluating rule 'C2001'. Rule configuration is missing.")); -$notification->setAssociatedRule(new ReportingDescriptorReference(0, 'C2001')); -$notification->setDescriptor(new ReportingDescriptorReference(1, 'CTN9999')); -$notification->setLevel('error'); -$invocation = new Invocation(true); -$invocation->addToolExecutionNotifications([$notification]); - -$result = new Result(new Message('...')); -$result->setRuleId('CTN9999'); - -$run = new Run($tool); -$run->addResults([$result]); -$run->addInvocations([$invocation]); - -``` + ```php title="examples/builder/reportingDescriptorReference.php" + --8<-- "examples/builder/reportingDescriptorReference.php" + ``` diff --git a/docs/reference/locationRelationship.md b/docs/reference/locationRelationship.md index db6e282..ece330e 100644 --- a/docs/reference/locationRelationship.md +++ b/docs/reference/locationRelationship.md @@ -4,170 +4,31 @@ A `locationRelationship` object specifies one or more directed relationships from one location object, which we refer to as theSource, to another one, which we refer to as theTarget. -![locationRelationship object](../assets/images/reference-location-relationship.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![locationRelationship object](../assets/images/reference-location-relationship.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "A result object with locationRelationship object" - }, - "locations": [ - { - "id": 0, - "physicalLocation": { - "artifactLocation": { - "uri": "f.h" - }, - "region": { - "startLine": 42 - } - }, - "relationships": [ - { - "target": 1, - "kinds": [ - "isIncludedBy" - ] - } - ] - } - ], - "relatedLocations": [ - { - "id": 1, - "physicalLocation": { - "artifactLocation": { - "uri": "g.h" - }, - "region": { - "startLine": 17 - } - }, - "relationships": [ - { - "target": 0, - "kinds": [ - "includes" - ] - }, - { - "target": 2, - "kinds": [ - "isIncludedBy" - ] - } - ] - }, - { - "id": 2, - "physicalLocation": { - "artifactLocation": { - "uri": "g.c" - }, - "region": { - "startLine": 8 - } - }, - "relationships": [ - { - "target": 1, - "kinds": [ - "includes" - ] - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php locationRelationship docs/assets/sarif 192` -See full [`examples/locationRelationship.php`][example-script] script into repository. + ```json title="docs/assets/sarif/locationRelationship.json" + --8<-- "docs/assets/sarif/locationRelationship.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/locationRelationship.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/locationRelationship.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/locationRelationship.php + ```php title="examples/locationRelationship.php" + --8<-- "examples/locationRelationship.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$location = []; -$physicalLocation = []; -$artifactLocation = []; -$region = []; -$relationships = []; - -$location[0] = new Location(); -$location[0]->setId(0); -$artifactLocation[0] = new ArtifactLocation(); -$artifactLocation[0]->setUri('f.h'); -$physicalLocation[0] = new PhysicalLocation($artifactLocation[0]); -$region[0] = new Region(42); -$physicalLocation[0]->setRegion($region[0]); -$location[0]->setPhysicalLocation($physicalLocation[0]); -$relationships[0] = new LocationRelationship(1); -$relationships[0]->addKinds(['isIncludedBy']); -$location[0]->addRelationships([$relationships[0]]); - -$location[1] = new Location(); -$location[1]->setId(1); -$artifactLocation[1] = new ArtifactLocation(); -$artifactLocation[1]->setUri('g.h'); -$physicalLocation[1] = new PhysicalLocation($artifactLocation[1]); -$region[1] = new Region(17); -$physicalLocation[1]->setRegion($region[1]); -$location[1]->setPhysicalLocation($physicalLocation[1]); -$relationships[1] = new LocationRelationship(0); -$relationships[1]->addKinds(['includes']); -$relationships[2] = new LocationRelationship(2); -$relationships[2]->addKinds(['isIncludedBy']); -$location[1]->addRelationships([$relationships[1], $relationships[2]]); - -$location[2] = new Location(); -$location[2]->setId(2); -$artifactLocation[2] = new ArtifactLocation(); -$artifactLocation[2]->setUri('g.c'); -$physicalLocation[2] = new PhysicalLocation($artifactLocation[2]); -$region[2] = new Region(8); -$physicalLocation[2]->setRegion($region[2]); -$location[2]->setPhysicalLocation($physicalLocation[2]); -$relationships[2] = new LocationRelationship(1); -$relationships[2]->addKinds(['includes']); -$location[2]->addRelationships([$relationships[2]]); - -$result = new Result(new Message('A result object with locationRelationship object')); -$result->addLocations([$location[0]]); -$result->addRelatedLocations([$location[1], $location[2]]); - -``` + ```php title="examples/builder/locationRelationship.php" + --8<-- "examples/builder/locationRelationship.php" + ``` diff --git a/docs/reference/logicalLocation.md b/docs/reference/logicalLocation.md index ffb03b9..b48db92 100644 --- a/docs/reference/logicalLocation.md +++ b/docs/reference/logicalLocation.md @@ -5,69 +5,31 @@ A `logicalLocation` object describes a logical location. A logical location is a location specified by a programmatic construct such as a namespace, a type, or a method, without regard to the physical location where the construct occurs. -![logicalLocation object](../assets/images/reference-logical-location.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![logicalLocation object](../assets/images/reference-logical-location.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "Psalm", - "version": "4.x-dev", - "informationUri": "https://psalm.de" - } - }, - "logicalLocations": [ - { - "name": "Hook", - "fullyQualifiedName": "Psalm\\Plugin\\Hook", - "kind": "namespace" - }, - { - "name": "afterAnalysis", - "fullyQualifiedName": "Psalm\\Plugin\\Hook\\AfterAnalysisInterface\\afterAnalysis", - "kind": "function" - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php logicalLocation docs/assets/sarif 192` -See full [`examples/logicalLocation.php`][example-script] script into repository. + ```json title="docs/assets/sarif/logicalLocation.json" + --8<-- "docs/assets/sarif/logicalLocation.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/logicalLocation.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/logicalLocation.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/logicalLocation.php + ```php title="examples/logicalLocation.php" + --8<-- "examples/logicalLocation.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$nsLocation = new LogicalLocation(); -$nsLocation->setName('Hook'); -$nsLocation->setFullyQualifiedName('Psalm\Plugin\Hook'); -$nsLocation->setKind('namespace'); - -$funcLocation = new LogicalLocation(); -$funcLocation->setName('afterAnalysis'); -$funcLocation->setFullyQualifiedName('Psalm\Plugin\Hook\AfterAnalysisInterface\afterAnalysis'); -$funcLocation->setKind('function'); - -$run = new Run($tool); -$run->addLogicalLocations([$nsLocation, $funcLocation]); - -``` + ```php title="examples/builder/logicalLocation.php" + --8<-- "examples/builder/logicalLocation.php" + ``` diff --git a/docs/reference/message.md b/docs/reference/message.md index ce40c16..4601de0 100644 --- a/docs/reference/message.md +++ b/docs/reference/message.md @@ -13,268 +13,108 @@ SARIF represents such a message with a `message` object, which offers the follow ## PlainText Example -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "ESLint", - "semanticVersion": "8.1.0", - "informationUri": "https://eslint.org", - "rules": [ - { - "id": "no-unused-vars", - "shortDescription": { - "text": "disallow unused variables" - }, - "helpUri": "https://eslint.org/docs/rules/no-unused-vars", - "properties": { - "category": "Variables" - } - } - ] - } - }, - "results": [ - { - "message": { - "text": "'x' is assigned a value but never used." - }, - "ruleId": "no-unused-vars", - "ruleIndex": 0, - "level": "error" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" + + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php message/plainText docs/assets/sarif 192` + + ```json title="docs/assets/sarif/message/plainText.json" + --8<-- "docs/assets/sarif/message/plainText.json" + ``` + +=== ":simple-php: Simple API" + + ```php title="examples/message/plainText.php" + --8<-- "examples/message/plainText.php" + ``` + +=== ":simple-php: Fluent Builder API" + + > [!NOTE] + > This alternative API is available since release 1.5.0 + + ```php title="examples/builder/message/plainText.php" + --8<-- "examples/builder/message/plainText.php" + ``` ## Formatted Example -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Variable '{0}' is uninitialized.", - "arguments": [ - "pBuffer" - ] - }, - "ruleId": "CA2101" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" + + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php message/formatted docs/assets/sarif 192` + + ```json title="docs/assets/sarif/message/formatted.json" + --8<-- "docs/assets/sarif/message/formatted.json" + ``` + +=== ":simple-php: Simple API" + + ```php title="examples/message/formatted.php" + --8<-- "examples/message/formatted.php" + ``` + +=== ":simple-php: Fluent Builder API" + + > [!NOTE] + > This alternative API is available since release 1.5.0 + + ```php title="examples/builder/message/formatted.php" + --8<-- "examples/builder/message/formatted.php" + ``` ## Embedded links Example -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Tainted data was used. The data came from [here](3)." - }, - "ruleId": "TNT0001", - "relatedLocations": [ - { - "id": 3, - "physicalLocation": { - "artifactLocation": { - "uri": "file:///C:/code/input.c" - }, - "region": { - "startLine": 25, - "startColumn": 19 - } - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" + + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php message/embeddedLinks docs/assets/sarif 192` + + ```json title="docs/assets/sarif/message/embeddedLinks.json" + --8<-- "docs/assets/sarif/message/embeddedLinks.json" + ``` + +=== ":simple-php: Simple API" + + ```php title="examples/message/embeddedLinks.php" + --8<-- "examples/message/embeddedLinks.php" + ``` + +=== ":simple-php: Fluent Builder API" + + > [!NOTE] + > This alternative API is available since release 1.5.0 + + ```php title="examples/builder/message/embeddedLinks.php" + --8<-- "examples/builder/message/embeddedLinks.php" + ``` ## String lookup Example -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CS0001", - "messageStrings": { - "default": { - "text": "This is the message text. It might be very long." - } - } - } - ] - } - }, - "results": [ - { - "message": { - "id": "default" - }, - "ruleId": "CS0001", - "ruleIndex": 0 - } - ] - } - ] -} -``` - -## How to generate - -See full [`examples/message/plainText.php`][example-script-1] script into repository. - -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/plainText.php`][example-builder-1] script into repository. - -[example-script-1]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/message/plainText.php -[example-builder-1]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/plainText.php - -```php -setLevel('error'); -$result->setRuleId('no-unused-vars'); -$result->setRuleIndex(0); - -``` - -See full [`examples/message/formatted.php`][example-script-2] script into repository. - -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/formatted.php`][example-builder-2] script into repository. - -[example-script-2]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/message/formatted.php -[example-builder-2]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/formatted.php - -```php -addArguments(['pBuffer']); -$result = new Result($message); -$result->setRuleId('CA2101'); - -``` - -See full [`examples/message/embeddedLinks.php`][example-script-3] script into repository. - -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/embeddedLinks.php`][example-builder-3] script into repository. - -[example-script-3]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/message/embeddedLinks.php -[example-builder-3]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/embeddedLinks.php - -```php -setRuleId('TNT0001'); -$location = new Location(); -$location->setId('3'); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('file:///C:/code/input.c'); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(25, 19)); -$location->setPhysicalLocation($physicalLocation); -$result->addRelatedLocations([$location]); - -``` - -See full [`examples/message/stringLookup.php`][example-script-4] script into repository. - -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/stringLookup.php`][example-builder-4] script into repository. - -[example-script-4]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/message/stringLookup.php -[example-builder-4]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/stringLookup.php - -```php - [!TIP] + > + > Generated with following command : `php ./resources/serialize.php message/stringLookup docs/assets/sarif 192` + + ```json title="docs/assets/sarif/message/stringLookup.json" + --8<-- "docs/assets/sarif/message/stringLookup.json" + ``` + +=== ":simple-php: Simple API" -use Bartlett\Sarif\Definition\Message; -use Bartlett\Sarif\Definition\MultiformatMessageString; -use Bartlett\Sarif\Definition\ReportingDescriptor; -use Bartlett\Sarif\Definition\Result; + ```php title="examples/message/stringLookup.php" + --8<-- "examples/message/stringLookup.php" + ``` -$rule = new ReportingDescriptor('no-unused-vars'); -$rule->setId('CS0001'); -$rule->addMessageStrings([ - 'default' => new MultiformatMessageString('This is the message text. It might be very long.'), -]); +=== ":simple-php: Fluent Builder API" -$message = new Message( - 'A message object can directly contain message strings in its text and markdown properties.' - . ' It can also indirectly refer to message strings through its id property.' -); -$result = new Result($message); -$result->setRuleId('CS0001'); -$result->setRuleIndex(0); -$result->setMessage(new Message('', 'default')); + > [!NOTE] + > This alternative API is available since release 1.5.0 -``` + ```php title="examples/builder/message/stringLookup.php" + --8<-- "examples/builder/message/stringLookup.php" + ``` diff --git a/docs/reference/node.md b/docs/reference/node.md index bd01a55..a8d11cb 100644 --- a/docs/reference/node.md +++ b/docs/reference/node.md @@ -3,97 +3,31 @@ A `node` object represents a node in the graph represented by the containing graph object, which we refer to as theGraph. -![node object](../assets/images/reference-node.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![node object](../assets/images/reference-node.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Have a look on this graph" - }, - "graphs": [ - { - "nodes": [ - { - "id": "n2" - }, - { - "id": "n3" - }, - { - "id": "n4" - }, - { - "id": "n1", - "children": [ - { - "id": "n3" - } - ] - } - ], - "edges": [ - { - "id": "e1", - "sourceNodeId": "n3", - "targetNodeId": "n4" - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php graph docs/assets/sarif 192` -See full [`examples/graph.php`][example-script] script into repository. + ```json title="docs/assets/sarif/graph.json" + --8<-- "docs/assets/sarif/graph.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/graph.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/graph.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/graph.php + ```php title="examples/graph.php" + --8<-- "examples/graph.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$nodes = []; -$nodes[2] = new Node('n2'); -$nodes[3] = new Node('n3'); -$nodes[4] = new Node('n4'); -$nodes[1] = new Node('n1'); -$nodes[1]->addChildren([$nodes[3]]); - -$edges = []; -$edges[1] = new Edge('e1', 'n3', 'n4'); - -$graph = new Graph(); -$graph->addNodes($nodes); -$graph->addEdges($edges); - -``` + ```php title="examples/builder/graph.php" + --8<-- "examples/builder/graph.php" + ``` diff --git a/docs/reference/notification.md b/docs/reference/notification.md index 4fe01e8..a667c6b 100644 --- a/docs/reference/notification.md +++ b/docs/reference/notification.md @@ -5,91 +5,31 @@ A `notification` object describes a condition encountered during the execution o which is relevant to the operation of the tool itself, as opposed to being relevant to an artifact being analyzed by the tool. Conditions relevant to artifacts being analyzed by a tool are represented by `result` objects. -![notification object](../assets/images/reference-notification.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![notification object](../assets/images/reference-notification.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CTN9999", - "shortDescription": { - "text": "First version of rule." - } - }, - { - "id": "CTN9999", - "shortDescription": { - "text": "Second version of rule." - } - } - ] - } - }, - "invocations": [ - { - "executionSuccessful": true, - "toolExecutionNotifications": [ - { - "message": { - "text": "Exception evaluating rule 'C2001'. Rule configuration is missing." - }, - "level": "error", - "descriptor": { - "index": 1, - "id": "CTN9999" - } - } - ] - } - ], - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CTN9999" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingDescriptorReference docs/assets/sarif 192` -See full [`examples/reportingDescriptorReference.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingDescriptorReference.json" + --8<-- "docs/assets/sarif/reportingDescriptorReference.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingDescriptorReference.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingDescriptorReference.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingDescriptorReference.php + ```php title="examples/reportingDescriptorReference.php" + --8<-- "examples/reportingDescriptorReference.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$notification = new Notification(new Message("Exception evaluating rule 'C2001'. Rule configuration is missing.")); -$notification->setAssociatedRule(new ReportingDescriptorReference(0, 'C2001')); -$notification->setDescriptor(new ReportingDescriptorReference(1, 'CTN9999')); -$notification->setLevel('error'); -$invocation = new Invocation(true); -$invocation->addToolExecutionNotifications([$notification]); - -``` + ```php title="examples/builder/reportingDescriptorReference.php" + --8<-- "examples/builder/reportingDescriptorReference.php" + ``` diff --git a/docs/reference/physicalLocation.md b/docs/reference/physicalLocation.md index 0e889d7..57aabfc 100644 --- a/docs/reference/physicalLocation.md +++ b/docs/reference/physicalLocation.md @@ -4,79 +4,31 @@ A `physicalLocation` object represents the physical location where a result was detected. A physical location specifies a reference to an artifact together with a region within that artifact. -![physicalLocation object](../assets/images/reference-physical-location.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![physicalLocation object](../assets/images/reference-physical-location.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Identify a physical location where a result was detected." - }, - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "ui/window.c", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 42 - } - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php physicalLocation docs/assets/sarif 192` -See full [`examples/physicalLocation.php`][example-script] script into repository. + ```json title="docs/assets/sarif/physicalLocation.json" + --8<-- "docs/assets/sarif/physicalLocation.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/physicalLocation.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/physicalLocation.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/physicalLocation.php + ```php title="examples/physicalLocation.php" + --8<-- "examples/physicalLocation.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 - -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('ui/window.c'); -$artifactLocation->setUriBaseId('SRCROOT'); - -$result = new Result(new Message('Identify a physical location where a result was detected.')); -$location = new Location(); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(42)); -$location->setPhysicalLocation($physicalLocation); -$result->addLocations([$location]); - -``` + ```php title="examples/builder/physicalLocation.php" + --8<-- "examples/builder/physicalLocation.php" + ``` diff --git a/docs/reference/rectangle.md b/docs/reference/rectangle.md index 7a6949f..40f27f5 100644 --- a/docs/reference/rectangle.md +++ b/docs/reference/rectangle.md @@ -5,88 +5,31 @@ A `rectangle` object specifies a rectangular area within an image. When a SARIF viewer displays an image, it MAY indicate the presence of these areas, for example, by highlighting them or surrounding them with a border. -![rectangle object](../assets/images/reference-rectangle.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![rectangle object](../assets/images/reference-rectangle.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "Have a look on screen shot provided" - }, - "attachments": [ - { - "artifactLocation": { - "uri": "file:///C:/ScanOutput/image001.png" - }, - "description": { - "text": "Screen shot" - }, - "rectangles": [ - { - "top": 80, - "left": 10, - "bottom": 5, - "right": 90 - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php rectangle docs/assets/sarif 192` -See full [`examples/rectangle.php`][example-script] script into repository. + ```json title="docs/assets/sarif/rectangle.json" + --8<-- "docs/assets/sarif/rectangle.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/rectangle.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/rectangle.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/rectangle.php + ```php title="examples/rectangle.php" + --8<-- "examples/rectangle.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$attachment = new Attachment(); -$attachment->setDescription(new Message('Screen shot')); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('file:///C:/ScanOutput/image001.png'); -$attachment->setArtifactLocation($artifactLocation); -$rectangle = new Rectangle(); -$rectangle->setTop(80); -$rectangle->setLeft(10); -$rectangle->setBottom(5); -$rectangle->setRight(90); -$attachment->addRectangles([$rectangle]); - -$result = new Result(new Message('Have a look on screen shot provided')); -$result->addAttachments([$attachment]); - -``` + ```php title="examples/builder/rectangle.php" + --8<-- "examples/builder/rectangle.php" + ``` diff --git a/docs/reference/replacement.md b/docs/reference/replacement.md index 110081a..24983aa 100644 --- a/docs/reference/replacement.md +++ b/docs/reference/replacement.md @@ -3,85 +3,31 @@ A `replacement` object represents the replacement of a single region of an artifact. -![replacement object](../assets/images/reference-replacement.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![replacement object](../assets/images/reference-replacement.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CA1001", - "fixes": [ - { - "artifactChanges": [ - { - "artifactLocation": { - "uri": "src/a.c" - }, - "replacements": [ - { - "deletedRegion": { - "startLine": 1, - "startColumn": 1, - "endLine": 1 - }, - "insertedContent": { - "text": "// " - } - } - ] - } - ] - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php fix docs/assets/sarif 192` -See full [`examples/fix.php`][example-script] script into repository. + ```json title="docs/assets/sarif/fix.json" + --8<-- "docs/assets/sarif/fix.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/fix.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/fix.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/fix.php + ```php title="examples/fix.php" + --8<-- "examples/fix.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('src/a.c'); -$replacement = new Replacement(new Region(1, 1, 1)); -$insertedContent = new ArtifactContent(); -$insertedContent->setText('// '); -$replacement->setInsertedContent($insertedContent); -$artifactChange = new ArtifactChange($artifactLocation, [$replacement]); - -``` + ```php title="examples/builder/fix.php" + --8<-- "examples/builder/fix.php" + ``` diff --git a/docs/reference/reportingConfiguration.md b/docs/reference/reportingConfiguration.md index 62fa59b..850b885 100644 --- a/docs/reference/reportingConfiguration.md +++ b/docs/reference/reportingConfiguration.md @@ -4,72 +4,31 @@ A `reportingConfiguration` object contains the information in a `reportingDescriptor` that a SARIF producer can modify at runtime, before executing its scan. -![reportingConfiguration object](../assets/images/reference-reporting-configuration.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![reportingConfiguration object](../assets/images/reference-reporting-configuration.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "SA2707", - "name": "LimitSourceLineLength", - "shortDescription": { - "text": "Limit source line length for readability." - }, - "defaultConfiguration": { - "enabled": true, - "level": "warning", - "rank": -1, - "parameters": { - "maxLength": 120 - } - } - } - ] - } - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingConfiguration docs/assets/sarif 192` -See full [`examples/reportingConfiguration.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingConfiguration.json" + --8<-- "docs/assets/sarif/reportingConfiguration.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingConfiguration.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingConfiguration.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingConfiguration.php + ```php title="examples/reportingConfiguration.php" + --8<-- "examples/reportingConfiguration.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$rule = new ReportingDescriptor('SA2707'); -$rule->setName('LimitSourceLineLength'); -$rule->setShortDescription(new MultiformatMessageString('Limit source line length for readability.')); -$reportingConf = new ReportingConfiguration(); -$propertyBag = new PropertyBag(); -$propertyBag->addProperty('maxLength', 120); -$reportingConf->setParameters($propertyBag); -$rule->setDefaultConfiguration($reportingConf); - -``` + ```php title="examples/builder/reportingConfiguration.php" + --8<-- "examples/builder/reportingConfiguration.php" + ``` diff --git a/docs/reference/reportingDescriptor.md b/docs/reference/reportingDescriptor.md index 2812151..aab8704 100644 --- a/docs/reference/reportingDescriptor.md +++ b/docs/reference/reportingDescriptor.md @@ -3,91 +3,31 @@ A `reportingDescriptor` object contains information that describes a "reporting item" generated by a tool. -![reportingDescriptor object](../assets/images/reference-reporting-descriptor.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![reportingDescriptor object](../assets/images/reference-reporting-descriptor.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CA1001", - "deprecatedIds": [ - "CA1000" - ] - }, - { - "id": "CA1002", - "deprecatedIds": [ - "CA1000" - ] - } - ] - } - }, - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CA1001", - "suppressions": [ - { - "kind": "inSource" - } - ], - "baselineState": "unchanged" - }, - { - "message": { - "text": "..." - }, - "ruleId": "CA1002", - "suppressions": [ - { - "kind": "inSource" - } - ], - "baselineState": "updated" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingDescriptor docs/assets/sarif 192` -See full [`examples/reportingDescriptor.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingDescriptor.json" + --8<-- "docs/assets/sarif/reportingDescriptor.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingDescriptor.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingDescriptor.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingDescriptor.php + ```php title="examples/reportingDescriptor.php" + --8<-- "examples/reportingDescriptor.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$driver = new ToolComponent('CodeScanner'); - -$rule1 = new ReportingDescriptor('CA1001'); -$rule1->addDeprecatedIds(['CA1000']); -$rule2 = new ReportingDescriptor('CA1002'); -$rule2->addDeprecatedIds(['CA1000']); -$driver->addRules([$rule1, $rule2]); - -``` + ```php title="examples/builder/reportingDescriptor.php" + --8<-- "examples/builder/reportingDescriptor.php" + ``` diff --git a/docs/reference/reportingDescriptorReference.md b/docs/reference/reportingDescriptorReference.md index 3dc2e5f..3d2e13c 100644 --- a/docs/reference/reportingDescriptorReference.md +++ b/docs/reference/reportingDescriptorReference.md @@ -5,91 +5,31 @@ A `reportingDescriptorReference` object identifies a particular `reportingDescri which we refer to as theDescriptor, among all `reportingDescriptor` objects defined by theTool, including those defined by theTool.driver and theTool.extensions. -![reportingDescriptorReference object](../assets/images/reference-reporting-descriptor-reference.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![reportingDescriptorReference object](../assets/images/reference-reporting-descriptor-reference.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CTN9999", - "shortDescription": { - "text": "First version of rule." - } - }, - { - "id": "CTN9999", - "shortDescription": { - "text": "Second version of rule." - } - } - ] - } - }, - "invocations": [ - { - "executionSuccessful": true, - "toolExecutionNotifications": [ - { - "message": { - "text": "Exception evaluating rule 'C2001'. Rule configuration is missing." - }, - "level": "error", - "descriptor": { - "index": 1, - "id": "CTN9999" - } - } - ] - } - ], - "results": [ - { - "message": { - "text": "..." - }, - "ruleId": "CTN9999" - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingDescriptorReference docs/assets/sarif 192` -See full [`examples/reportingDescriptorReference.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingDescriptorReference.json" + --8<-- "docs/assets/sarif/reportingDescriptorReference.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingDescriptorReference.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingDescriptorReference.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingDescriptorReference.php + ```php title="examples/reportingDescriptorReference.php" + --8<-- "examples/reportingDescriptorReference.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$notification = new Notification(new Message("Exception evaluating rule 'C2001'. Rule configuration is missing.")); -$notification->setAssociatedRule(new ReportingDescriptorReference(0, 'C2001')); -$notification->setDescriptor(new ReportingDescriptorReference(1, 'CTN9999')); -$notification->setLevel('error'); -$invocation = new Invocation(true); -$invocation->addToolExecutionNotifications([$notification]); - -``` + ```php title="examples/builder/reportingDescriptorReference.php" + --8<-- "examples/builder/reportingDescriptorReference.php" + ``` diff --git a/docs/reference/reportingDescriptorRelationship.md b/docs/reference/reportingDescriptorRelationship.md index 0509866..601b0c6 100644 --- a/docs/reference/reportingDescriptorRelationship.md +++ b/docs/reference/reportingDescriptorRelationship.md @@ -4,79 +4,31 @@ A `reportingDescriptorRelationship` object specifies one or more directed relationships from one `reportingDescriptor` object, which we refer to as theSource, to another one, which we refer to as theTarget. -![reportingDescriptorRelationship object](../assets/images/reference-reporting-descriptor-relationship.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![reportingDescriptorRelationship object](../assets/images/reference-reporting-descriptor-relationship.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CA1000", - "relationships": [ - { - "target": { - "index": 0, - "id": "327", - "guid": "33333333-0000-1111-8888-111111111111", - "toolComponent": { - "name": "CWE", - "guid": "33333333-0000-1111-8888-000000000000" - } - }, - "kinds": [ - "superset" - ] - } - ] - } - ] - } - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingDescriptorRelationship docs/assets/sarif 192` -See full [`examples/reportingDescriptorRelationship.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingDescriptorRelationship.json" + --8<-- "docs/assets/sarif/reportingDescriptorRelationship.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingDescriptorRelationship.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingDescriptorRelationship.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingDescriptorRelationship.php + ```php title="examples/reportingDescriptorRelationship.php" + --8<-- "examples/reportingDescriptorRelationship.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$rule = new ReportingDescriptor('CA1000'); - -$target = new ReportingDescriptorReference(0, '327', '33333333-0000-1111-8888-111111111111'); -$toolComponent = new ToolComponentReference(); -$toolComponent->setName('CWE'); -$toolComponent->setGuid('33333333-0000-1111-8888-000000000000'); -$target->setToolComponent($toolComponent); - -$relationship = new ReportingDescriptorRelationship($target); -$relationship->addKinds(['superset']); -$rule->addRelationships([$relationship]); - -``` + ```php title="examples/builder/reportingDescriptorRelationship.php" + --8<-- "examples/builder/reportingDescriptorRelationship.php" + ``` diff --git a/docs/reference/result.md b/docs/reference/result.md index 3108845..ee25a20 100644 --- a/docs/reference/result.md +++ b/docs/reference/result.md @@ -3,96 +3,31 @@ A `result` object describes a single result detected by an analysis tool. -![result object](../assets/images/reference-result.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![result object](../assets/images/reference-result.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CA2101", - "shortDescription": { - "text": "Specify marshaling for P/Invoke string arguments." - } - }, - { - "id": "CA5350", - "shortDescription": { - "text": "Do not use weak cryptographic algorithms." - } - } - ] - } - }, - "results": [ - { - "message": { - "text": "Result on rule 0" - }, - "ruleId": "CA2101", - "ruleIndex": 0 - }, - { - "message": { - "text": "Result on rule 1" - }, - "ruleId": "CA5350/md5", - "ruleIndex": 1 - }, - { - "message": { - "text": "Another result on rule 1" - }, - "ruleId": "CA5350/sha-1", - "ruleIndex": 1 - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php result docs/assets/sarif 192` -See full [`examples/result.php`][example-script] script into repository. + ```json title="docs/assets/sarif/result.json" + --8<-- "docs/assets/sarif/result.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/result.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/result.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/result.php + ```php title="examples/result.php" + --8<-- "examples/result.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$result1 = new Result(new Message('Result on rule 0')); -$result1->setRuleId('CA2101'); -$result1->setRuleIndex(0); - -$result2 = new Result(new Message('Result on rule 1')); -$result2->setRuleId('CA5350/md5'); -$result2->setRuleIndex(1); - -$result3 = new Result(new Message('Another result on rule 1')); -$result3->setRuleId('CA5350/sha-1'); -$result3->setRuleIndex(1); - -$run = new Run($tool); -$run->addResults([$result1, $result2, $result3]); - -``` + ```php title="examples/builder/result.php" + --8<-- "examples/builder/result.php" + ``` diff --git a/docs/reference/resultProvenance.md b/docs/reference/resultProvenance.md index ca17e43..3267aaf 100644 --- a/docs/reference/resultProvenance.md +++ b/docs/reference/resultProvenance.md @@ -3,92 +3,31 @@ A `resultProvenance` object contains information about the how and when theResult was detected. -![resultProvenance object](../assets/images/reference-result-provenance.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![resultProvenance object](../assets/images/reference-result-provenance.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "SarifSamples", - "version": "1.0", - "informationUri": "https://github.com/microsoft/sarif-tutorials/" - } - }, - "results": [ - { - "message": { - "text": "Assertions are unreliable." - }, - "ruleId": "Assertions", - "provenance": { - "conversionSources": [ - { - "artifactLocation": { - "uri": "CodeScanner.log", - "uriBaseId": "LOGSROOT" - }, - "region": { - "startLine": 3, - "startColumn": 3, - "endLine": 12, - "endColumn": 13, - "snippet": { - "text": "..." - } - } - } - ] - } - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php resultProvenance docs/assets/sarif 192` -See full [`examples/resultProvenance.php`][example-script] script into repository. + ```json title="docs/assets/sarif/resultProvenance.json" + --8<-- "docs/assets/sarif/resultProvenance.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/resultProvenance.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/resultProvenance.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/resultProvenance.php + ```php title="examples/resultProvenance.php" + --8<-- "examples/resultProvenance.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$provenance = new ResultProvenance(); -$fromSources = []; -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('CodeScanner.log'); -$artifactLocation->setUriBaseId('LOGSROOT'); -$fromSources[0] = new PhysicalLocation($artifactLocation); -$region = new Region(3, 3, 12, 13); -$snippet = new ArtifactContent(); -$snippet->setText('...'); -$region->setSnippet($snippet); -$fromSources[0]->setRegion($region); - -$provenance->addConversionSources($fromSources); - -$result = new Result(new Message('Assertions are unreliable.')); -$result->setProvenance($provenance); - -``` + ```php title="examples/builder/resultProvenance.php" + --8<-- "examples/builder/resultProvenance.php" + ``` diff --git a/docs/reference/run.md b/docs/reference/run.md index e9f4fe2..eb0b76d 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -3,53 +3,31 @@ A `run` object describes a single run of an analysis tool and contains the output of that run. -![run object](../assets/images/reference-run.graphviz.svg) - -## Example - -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "Psalm", - "version": "4.x-dev", - "informationUri": "https://psalm.de" - } - }, - "properties": { - "stableId": "Nightly static analysis run" - }, - "results": [] - } - ] -} -``` - -## How to generate - -See full [`examples/run.php`][example-script] script into repository. - -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/run.php`][example-builder] script into repository. - -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/run.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/run.php - -```php - [!TIP] + > + > Generated with following command : `php ./resources/serialize.php run docs/assets/sarif 192` + + ```json title="docs/assets/sarif/run.json" + --8<-- "docs/assets/sarif/run.json" + ``` + +=== ":simple-php: Simple API" + + ```php title="examples/run.php" + --8<-- "examples/run.php" + ``` + +=== ":simple-php: Fluent Builder API" + + > [!NOTE] + > This alternative API is available since release 1.5.0 + + ```php title="examples/builder/run.php" + --8<-- "examples/builder/run.php" + ``` diff --git a/docs/reference/runAutomationDetails.md b/docs/reference/runAutomationDetails.md index edd5a72..97a49f4 100644 --- a/docs/reference/runAutomationDetails.md +++ b/docs/reference/runAutomationDetails.md @@ -3,83 +3,31 @@ A `runAutomationDetails` object contains information that specifies theRun’s identity and role within an engineering system. -![runAutomationDetails object](../assets/images/reference-run-automation-details.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![runAutomationDetails object](../assets/images/reference-run-automation-details.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "automationDetails": { - "description": { - "text": "This is the {0} nightly run of the Credential Scanner tool on all product binaries in the '{1}' branch of the '{2}' repo. The scanned binaries are architecture '{3}' and build type '{4}'.", - "arguments": [ - "October 10, 2018", - "master", - "sarif-sdk", - "x86", - "debug" - ] - }, - "id": "Nightly CredScan run for sarif-sdk/master/x86/debug/2018-10-05", - "guid": "11111111-1111-1111-8888-111111111111", - "correlationGuid": "22222222-2222-1111-8888-222222222222" - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php runAutomationDetails docs/assets/sarif 192` -See full [`examples/runAutomationDetails.php`][example-script] script into repository. + ```json title="docs/assets/sarif/runAutomationDetails.json" + --8<-- "docs/assets/sarif/runAutomationDetails.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/runAutomationDetails.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/runAutomationDetails.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/runAutomationDetails.php + ```php title="examples/runAutomationDetails.php" + --8<-- "examples/runAutomationDetails.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$automationDetails = new RunAutomationDetails(); - -$text = "This is the {0} nightly run of the Credential Scanner tool on" . - " all product binaries in the '{1}' branch of the '{2}' repo.". - " The scanned binaries are architecture '{3}' and build type '{4}'."; -$description = new Message($text); -$description->addArguments([ - "October 10, 2018", - "master", - "sarif-sdk", - "x86", - "debug", -]); -$automationDetails->setDescription($description); -$automationDetails->setId('Nightly CredScan run for sarif-sdk/master/x86/debug/2018-10-05'); -$automationDetails->setGuid('11111111-1111-1111-8888-111111111111'); -$automationDetails->setCorrelationGuid('22222222-2222-1111-8888-222222222222'); - -$run = new Run($tool); -$run->setAutomationDetails($automationDetails); - -``` + ```php title="examples/builder/runAutomationDetails.php" + --8<-- "examples/builder/runAutomationDetails.php" + ``` diff --git a/docs/reference/sarifLog.md b/docs/reference/sarifLog.md index 8debe5d..69a5ead 100644 --- a/docs/reference/sarifLog.md +++ b/docs/reference/sarifLog.md @@ -3,34 +3,31 @@ A `sarifLog` object specifies the version of the file format and contains the output from one or more runs. -![sarifLog object](../assets/images/reference-sarif-log.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![sarifLog object](../assets/images/reference-sarif-log.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php sarifLog docs/assets/sarif 192` -See full [`examples/sarifLog.php`][example-script] script into repository. + ```json title="docs/assets/sarif/sarifLog.json" + --8<-- "docs/assets/sarif/sarifLog.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/sarifLog.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/sarifLog.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/sarifLog.php + ```php title="examples/sarifLog.php" + --8<-- "examples/sarifLog.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$log = new SarifLog(); - -``` + ```php title="examples/builder/sarifLog.php" + --8<-- "examples/builder/sarifLog.php" + ``` diff --git a/docs/reference/specialLocations.md b/docs/reference/specialLocations.md index 5c5d7ef..dd2effb 100644 --- a/docs/reference/specialLocations.md +++ b/docs/reference/specialLocations.md @@ -3,87 +3,31 @@ A `specialLocations` object defines locations of special significance to SARIF consumers. -![specialLocations object](../assets/images/reference-special-locations.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![specialLocations object](../assets/images/reference-special-locations.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "originalUriBaseIds": { - "WEBHOST": { - "uri": "http://www.example.com/" - }, - "ROOT": { - "uri": "file:///" - }, - "HOME": { - "uri": "home/user/", - "uriBaseId": "ROOT" - }, - "PACKAGE": { - "uri": "mySoftware/", - "uriBaseId": "HOME" - }, - "SRC": { - "uri": "src/", - "uriBaseId": "PACKAGE" - } - }, - "specialLocations": { - "displayBase": { - "uriBaseId": "PACKAGE" - } - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php specialLocations docs/assets/sarif 192` -See full [`examples/specialLocations.php`][example-script] script into repository. + ```json title="docs/assets/sarif/specialLocations.json" + --8<-- "docs/assets/sarif/specialLocations.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/specialLocations.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/specialLocations.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/specialLocations.php + ```php title="examples/specialLocations.php" + --8<-- "examples/specialLocations.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$package = new ArtifactLocation(); -$package->setUri('mySoftware/'); -$package->setUriBaseId('HOME'); - -$run = new Run($tool); -$run->addAdditionalProperties([ - 'PACKAGE' => $package, -]); - -$specialLocations = new SpecialLocations(); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri(''); -$artifactLocation->setUriBaseId('PACKAGE'); -$specialLocations->setDisplayBase($artifactLocation); - -$run->setSpecialLocations($specialLocations); - -``` + ```php title="examples/builder/specialLocations.php" + --8<-- "examples/builder/specialLocations.php" + ``` diff --git a/docs/reference/stack.md b/docs/reference/stack.md index f5aa068..99c2e1c 100644 --- a/docs/reference/stack.md +++ b/docs/reference/stack.md @@ -4,130 +4,31 @@ A `stack` object describes a single call stack. A call stack is a sequence of nested function calls, each of which is referred to as a stack frame. -![stack object](../assets/images/reference-stack.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![stack object](../assets/images/reference-stack.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "SarifSamples", - "version": "1.0", - "informationUri": "https://github.com/microsoft/sarif-tutorials/" - } - }, - "results": [ - { - "message": { - "text": "Uninitialized variable." - }, - "ruleId": "TUT1001", - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "collections/list.h", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 15 - } - }, - "logicalLocations": [ - { - "fullyQualifiedName": "collections::list::add" - } - ] - } - ], - "stacks": [ - { - "frames": [ - { - "location": { - "physicalLocation": { - "artifactLocation": { - "uri": "collections/list.h", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 110, - "startColumn": 15 - } - }, - "logicalLocations": [ - { - "fullyQualifiedName": "collections::list::add_core" - } - ] - }, - "module": "platform", - "threadId": 52, - "parameters": [ - "null", - "0", - "14" - ] - } - ], - "message": { - "text": "Call stack resulting from usage of uninitialized variable." - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php stack docs/assets/sarif 192` -See full [`examples/stack.php`][example-script] script into repository. + ```json title="docs/assets/sarif/stack.json" + --8<-- "docs/assets/sarif/stack.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/stack.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/stack.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/stack.php + ```php title="examples/stack.php" + --8<-- "examples/stack.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$frame = new StackFrame(); - -$location = new Location(); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('collections/list.h'); -$artifactLocation->setUriBaseId('SRCROOT'); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(110, 15)); -$location->setPhysicalLocation($physicalLocation); -$logicalLocation = new LogicalLocation(); -$logicalLocation->setFullyQualifiedName('collections::list::add_core'); -$location->addLogicalLocations([$logicalLocation]); -$frame->setLocation($location); -$frame->setModule('platform'); -$frame->setThreadId(52); -$frame->addParameters(['null', '0', '14']); - -$stack = new Stack([$frame]); -$stack->setMessage(new Message('Call stack resulting from usage of uninitialized variable.')); - -``` + ```php title="examples/builder/stack.php" + --8<-- "examples/builder/stack.php" + ``` diff --git a/docs/reference/stackFrame.md b/docs/reference/stackFrame.md index 019e7d2..85165e3 100644 --- a/docs/reference/stackFrame.md +++ b/docs/reference/stackFrame.md @@ -3,130 +3,31 @@ A `stackFrame` object describes a single stack frame within a call stack. -![stackFrame object](../assets/images/reference-stack-frame.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![stackFrame object](../assets/images/reference-stack-frame.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "SarifSamples", - "version": "1.0", - "informationUri": "https://github.com/microsoft/sarif-tutorials/" - } - }, - "results": [ - { - "message": { - "text": "Uninitialized variable." - }, - "ruleId": "TUT1001", - "locations": [ - { - "physicalLocation": { - "artifactLocation": { - "uri": "collections/list.h", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 15 - } - }, - "logicalLocations": [ - { - "fullyQualifiedName": "collections::list::add" - } - ] - } - ], - "stacks": [ - { - "frames": [ - { - "location": { - "physicalLocation": { - "artifactLocation": { - "uri": "collections/list.h", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 110, - "startColumn": 15 - } - }, - "logicalLocations": [ - { - "fullyQualifiedName": "collections::list::add_core" - } - ] - }, - "module": "platform", - "threadId": 52, - "parameters": [ - "null", - "0", - "14" - ] - } - ], - "message": { - "text": "Call stack resulting from usage of uninitialized variable." - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php stack docs/assets/sarif 192` -See full [`examples/stack.php`][example-script] script into repository. + ```json title="docs/assets/sarif/stack.json" + --8<-- "docs/assets/sarif/stack.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/stack.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/stack.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/stack.php + ```php title="examples/stack.php" + --8<-- "examples/stack.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$frame = new StackFrame(); - -$location = new Location(); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('collections/list.h'); -$artifactLocation->setUriBaseId('SRCROOT'); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(110, 15)); -$location->setPhysicalLocation($physicalLocation); -$logicalLocation = new LogicalLocation(); -$logicalLocation->setFullyQualifiedName('collections::list::add_core'); -$location->addLogicalLocations([$logicalLocation]); -$frame->setLocation($location); -$frame->setModule('platform'); -$frame->setThreadId(52); -$frame->addParameters(['null', '0', '14']); - -$stack = new Stack([$frame]); -$stack->setMessage(new Message('Call stack resulting from usage of uninitialized variable.')); - -``` + ```php title="examples/builder/stack.php" + --8<-- "examples/builder/stack.php" + ``` diff --git a/docs/reference/suppression.md b/docs/reference/suppression.md index eb0b625..49c49b5 100644 --- a/docs/reference/suppression.md +++ b/docs/reference/suppression.md @@ -3,67 +3,31 @@ A `suppression` object describes a request to suppress a result. -![suppression object](../assets/images/reference-suppression.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![suppression object](../assets/images/reference-suppression.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "Psalm", - "version": "4.x-dev", - "informationUri": "https://psalm.de" - } - }, - "results": [ - { - "message": { - "text": "Request to suppress a result" - }, - "suppressions": [ - { - "kind": "inSource", - "guid": "11111111-1111-1111-8888-111111111111", - "status": "underReview", - "justification": "result outdated" - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php suppression docs/assets/sarif 192` -See full [`examples/suppression.php`][example-script] script into repository. + ```json title="docs/assets/sarif/suppression.json" + --8<-- "docs/assets/sarif/suppression.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/suppression.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/suppression.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/suppression.php + ```php title="examples/suppression.php" + --8<-- "examples/suppression.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$suppression = new Suppression('inSource'); -$suppression->setGuid('11111111-1111-1111-8888-111111111111'); -$suppression->setStatus('underReview'); -$suppression->setJustification('result outdated'); - -$result = new Result(new Message('Request to suppress a result')); -$result->addSuppressions([$suppression]); - -``` + ```php title="examples/builder/suppression.php" + --8<-- "examples/builder/suppression.php" + ``` diff --git a/docs/reference/threadFlow.md b/docs/reference/threadFlow.md index 7421a02..c0002e8 100644 --- a/docs/reference/threadFlow.md +++ b/docs/reference/threadFlow.md @@ -4,120 +4,31 @@ A `threadFlow` object is a sequence of code locations that specify a possible path through a single thread of execution such as an operating system thread or a fiber. -![threadFlow object](../assets/images/reference-thread-flow.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![threadFlow object](../assets/images/reference-thread-flow.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "A result object" - }, - "codeFlows": [ - { - "threadFlows": [ - { - "locations": [ - { - "location": { - "physicalLocation": { - "artifactLocation": { - "uri": "ui/window.c", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 42 - } - } - }, - "state": { - "x": { - "text": "42" - }, - "y": { - "text": "54" - }, - "x+y": { - "text": "96" - } - }, - "nestingLevel": 0, - "executionOrder": 2 - } - ], - "id": "thread-123", - "message": { - "text": "A threadFlow object" - } - } - ], - "message": { - "text": "A codeFlow object" - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php codeFlow docs/assets/sarif 192` -See full [`examples/codeFlow.php`][example-script] script into repository. + ```json title="docs/assets/sarif/codeFlow.json" + --8<-- "docs/assets/sarif/codeFlow.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/codeFlow.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/codeFlow.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/codeFlow.php + ```php title="examples/codeFlow.php" + --8<-- "examples/codeFlow.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$threadFlowLocation = new ThreadFlowLocation(); -$location = new Location(); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('ui/window.c'); -$artifactLocation->setUriBaseId('SRCROOT'); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(42)); -$location->setPhysicalLocation($physicalLocation); -$threadFlowLocation->setLocation($location); -$threadFlowLocation->addAdditionalProperties([ - 'x' => new MultiformatMessageString('42'), - 'y' => new MultiformatMessageString('54'), - 'x+y' => new MultiformatMessageString('96'), -]); -$threadFlowLocation->setNestingLevel(0); -$threadFlowLocation->setExecutionOrder(2); - -$threadFlow = new ThreadFlow([$threadFlowLocation]); -$threadFlow->setId('thread-123'); -$threadFlow->setMessage(new Message('A threadFlow object')); - -``` + ```php title="examples/builder/codeFlow.php" + --8<-- "examples/builder/codeFlow.php" + ``` diff --git a/docs/reference/threadFlowLocation.md b/docs/reference/threadFlowLocation.md index 0987e5d..8d91b8d 100644 --- a/docs/reference/threadFlowLocation.md +++ b/docs/reference/threadFlowLocation.md @@ -4,114 +4,31 @@ A `threadFlowLocation` object represents a location visited by an analysis tool in the course of simulating or monitoring the execution of a program. -![threadFlowLocation object](../assets/images/reference-thread-flow-location.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![threadFlowLocation object](../assets/images/reference-thread-flow-location.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "results": [ - { - "message": { - "text": "A result object" - }, - "codeFlows": [ - { - "threadFlows": [ - { - "locations": [ - { - "location": { - "physicalLocation": { - "artifactLocation": { - "uri": "ui/window.c", - "uriBaseId": "SRCROOT" - }, - "region": { - "startLine": 42 - } - } - }, - "state": { - "x": { - "text": "42" - }, - "y": { - "text": "54" - }, - "x+y": { - "text": "96" - } - }, - "nestingLevel": 0, - "executionOrder": 2 - } - ], - "id": "thread-123", - "message": { - "text": "A threadFlow object" - } - } - ], - "message": { - "text": "A codeFlow object" - } - } - ] - } - ] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php codeFlow docs/assets/sarif 192` -See full [`examples/codeFlow.php`][example-script] script into repository. + ```json title="docs/assets/sarif/codeFlow.json" + --8<-- "docs/assets/sarif/codeFlow.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/codeFlow.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/codeFlow.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/codeFlow.php + ```php title="examples/codeFlow.php" + --8<-- "examples/codeFlow.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$threadFlowLocation = new ThreadFlowLocation(); -$location = new Location(); -$artifactLocation = new ArtifactLocation(); -$artifactLocation->setUri('ui/window.c'); -$artifactLocation->setUriBaseId('SRCROOT'); -$physicalLocation = new PhysicalLocation($artifactLocation); -$physicalLocation->setRegion(new Region(42)); -$location->setPhysicalLocation($physicalLocation); -$threadFlowLocation->setLocation($location); -$threadFlowLocation->addAdditionalProperties([ - 'x' => new MultiformatMessageString('42'), - 'y' => new MultiformatMessageString('54'), - 'x+y' => new MultiformatMessageString('96'), -]); -$threadFlowLocation->setNestingLevel(0); -$threadFlowLocation->setExecutionOrder(2); - -``` + ```php title="examples/builder/codeFlow.php" + --8<-- "examples/builder/codeFlow.php" + ``` diff --git a/docs/reference/tool.md b/docs/reference/tool.md index becd044..7452267 100644 --- a/docs/reference/tool.md +++ b/docs/reference/tool.md @@ -3,56 +3,31 @@ A `tool` object describes the analysis tool or converter that was run. -![tool object](../assets/images/reference-tool.graphviz.svg) - -## Example - -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "fullName": "CodeScanner 1.1, Developer Preview (en-US)", - "version": "1.1.2b12", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - }, - "extensions": [ - { - "name": "CodeScanner Security Rules", - "version": "3.1" - } - ] - }, - "results": [] - } - ] -} -``` - -## How to generate - -See full [`examples/tool.php`][example-script] script into repository. - -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/tool.php`][example-builder] script into repository. - -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/tool.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/tool.php - -```php - [!TIP] + > + > Generated with following command : `php ./resources/serialize.php tool docs/assets/sarif 192` + + ```json title="docs/assets/sarif/tool.json" + --8<-- "docs/assets/sarif/tool.json" + ``` + +=== ":simple-php: Simple API" + + ```php title="examples/tool.php" + --8<-- "examples/tool.php" + ``` + +=== ":simple-php: Fluent Builder API" + + > [!NOTE] + > This alternative API is available since release 1.5.0 + + ```php title="examples/builder/tool.php" + --8<-- "examples/builder/tool.php" + ``` diff --git a/docs/reference/toolComponentReference.md b/docs/reference/toolComponentReference.md index 23b5aa9..1a3eb12 100644 --- a/docs/reference/toolComponentReference.md +++ b/docs/reference/toolComponentReference.md @@ -4,77 +4,31 @@ A `toolComponentReference` object identifies a particular `toolComponent` object, either theTool.driver or an element of theTool.extensions. We refer to the identified toolComponent object as theComponent. -![toolComponentReference object](../assets/images/reference-tool-component-reference.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![toolComponentReference object](../assets/images/reference-tool-component-reference.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "rules": [ - { - "id": "CA1000", - "relationships": [ - { - "target": { - "index": 0, - "id": "327", - "guid": "33333333-0000-1111-8888-111111111111", - "toolComponent": { - "name": "CWE", - "guid": "33333333-0000-1111-8888-000000000000" - } - }, - "kinds": [ - "superset" - ] - } - ] - } - ] - } - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php reportingDescriptorRelationship docs/assets/sarif 192` -See full [`examples/reportingDescriptorRelationship.php`][example-script] script into repository. + ```json title="docs/assets/sarif/reportingDescriptorRelationship.json" + --8<-- "docs/assets/sarif/reportingDescriptorRelationship.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/reportingDescriptorRelationship.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/reportingDescriptorRelationship.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/reportingDescriptorRelationship.php + ```php title="examples/reportingDescriptorRelationship.php" + --8<-- "examples/reportingDescriptorRelationship.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$target = new ReportingDescriptorReference(0, '327', '33333333-0000-1111-8888-111111111111'); -$toolComponent = new ToolComponentReference(); -$toolComponent->setName('CWE'); -$toolComponent->setGuid('33333333-0000-1111-8888-000000000000'); -$target->setToolComponent($toolComponent); - -``` + ```php title="examples/builder/reportingDescriptorRelationship.php" + --8<-- "examples/builder/reportingDescriptorRelationship.php" + ``` diff --git a/docs/reference/translationMetadata.md b/docs/reference/translationMetadata.md index 9b343fb..399bc06 100644 --- a/docs/reference/translationMetadata.md +++ b/docs/reference/translationMetadata.md @@ -3,72 +3,31 @@ A `translationMetadata` object defines locations of special significance to SARIF consumers. -![translationMetadata object](../assets/images/reference-translation-metadata.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![translationMetadata object](../assets/images/reference-translation-metadata.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "(fr-FR translation)", - "fullName": "(fr-FR translation of translated component\u2019s full name)", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev", - "language": "fr-FR", - "translationMetadata": { - "name": "CodeScanner translation for fr-FR", - "fullName": "CodeScanner translation for fr-FR by Example Corp.", - "shortDescription": { - "text": "A good translation" - }, - "fullDescription": { - "text": "A good translation performed by native en-US speakers." - } - } - } - }, - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php translationMetadata docs/assets/sarif 192` -See full [`examples/translationMetadata.php`][example-script] script into repository. + ```json title="docs/assets/sarif/translationMetadata.json" + --8<-- "docs/assets/sarif/translationMetadata.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/translationMetadata.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/translationMetadata.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/translationMetadata.php + ```php title="examples/translationMetadata.php" + --8<-- "examples/translationMetadata.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$driver = new ToolComponent('CodeScanner'); - -$translationMetadata = new TranslationMetadata('CodeScanner translation for fr-FR'); -$translationMetadata->setFullName('CodeScanner translation for fr-FR by Example Corp.'); -$translationMetadata->setShortDescription( - new MultiformatMessageString('A good translation') -); -$translationMetadata->setFullDescription( - new MultiformatMessageString('A good translation performed by native en-US speakers.') -); -$driver->setTranslationMetadata($translationMetadata); - -$driver->setName('(fr-FR translation)'); -$driver->setFullName('(fr-FR translation of translated component’s full name)'); - -``` + ```php title="examples/builder/translationMetadata.php" + --8<-- "examples/builder/translationMetadata.php" + ``` diff --git a/docs/reference/versionControlDetails.md b/docs/reference/versionControlDetails.md index 24fb355..e1b11c0 100644 --- a/docs/reference/versionControlDetails.md +++ b/docs/reference/versionControlDetails.md @@ -4,96 +4,31 @@ A `versionControlDetails` object specifies the information necessary to retrieve from a version control system (VCS) the correct revision of the files that were scanned during the run. -![versionControlDetails object](../assets/images/reference-version-control-details.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![versionControlDetails object](../assets/images/reference-version-control-details.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "AndroidStudio", - "semanticVersion": "1.0.0-beta.1", - "informationUri": "https://android-studion.dev" - } - }, - "versionControlProvenance": [ - { - "repositoryUri": "https://github.com/example-corp/package", - "revisionId": "b87c4e9", - "mappedTo": { - "uriBaseId": "PACKAGE_ROOT" - } - }, - { - "repositoryUri": "https://github.com/example-corp/plugin1", - "revisionId": "cafdac7", - "mappedTo": { - "uri": "plugin1", - "uriBaseId": "PACKAGE_ROOT" - } - }, - { - "repositoryUri": "https://github.com/example-corp/plugin2", - "revisionId": "d0dc2c0", - "mappedTo": { - "uri": "plugin2", - "uriBaseId": "PACKAGE_ROOT" - } - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php versionControlDetails docs/assets/sarif 192` -See full [`examples/versionControlDetails.php`][example-script] script into repository. + ```json title="docs/assets/sarif/versionControlDetails.json" + --8<-- "docs/assets/sarif/versionControlDetails.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/versionControlDetails.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/versionControlDetails.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/versionControlDetails.php + ```php title="examples/versionControlDetails.php" + --8<-- "examples/versionControlDetails.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$tool = new Tool($driver); - -$package = new VersionControlDetails('https://github.com/example-corp/package'); -$package->setRevisionId('b87c4e9'); -$packageMappedTo = new ArtifactLocation(); -$packageMappedTo->setUriBaseId('PACKAGE_ROOT'); -$package->setMappedTo($packageMappedTo); - -$plugin1 = new VersionControlDetails('https://github.com/example-corp/plugin1'); -$plugin1->setRevisionId('cafdac7'); -$plugin1MappedTo = new ArtifactLocation(); -$plugin1MappedTo->setUriBaseId('PACKAGE_ROOT'); -$plugin1MappedTo->setUri('plugin1'); -$plugin1->setMappedTo($plugin1MappedTo); - -$plugin2 = new VersionControlDetails('https://github.com/example-corp/plugin2'); -$plugin2->setRevisionId('d0dc2c0'); -$plugin2MappedTo = new ArtifactLocation(); -$plugin2MappedTo->setUriBaseId('PACKAGE_ROOT'); -$plugin2MappedTo->setUri('plugin2'); -$plugin2->setMappedTo($plugin2MappedTo); - -$run = new Run($tool); -$run->addVersionControlDetails([$package, $plugin1, $plugin2]); - -``` + ```php title="examples/builder/versionControlDetails.php" + --8<-- "examples/builder/versionControlDetails.php" + ``` diff --git a/docs/reference/webRequest.md b/docs/reference/webRequest.md index ad33c4c..fe0efb9 100644 --- a/docs/reference/webRequest.md +++ b/docs/reference/webRequest.md @@ -3,90 +3,31 @@ A `webRequest` object describes an HTTP request (RFC7230). -![webRequest object](../assets/images/reference-web-request.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![webRequest object](../assets/images/reference-web-request.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "webRequests": [ - { - "protocol": "http", - "version": "1.1", - "target": "httpbin.org/bearer", - "method": "GET", - "headers": { - "accept": "application/json", - "Authorization": "none" - } - } - ], - "webResponses": [ - { - "protocol": "http", - "version": "1.1", - "statusCode": 401, - "reasonPhrase": "Error: UNAUTHORIZED", - "headers": { - "access-control-allow-credentials": "true", - "access-control-allow-origin": "*", - "connection": "keep-alive", - "content-length": "0", - "content-type": "text/html; charset=utf-8", - "date": "Sun, 07 Nov 2021 08:59:53 GMT", - "server": "gunicorn/19.9.0", - "www-authenticate": "Bearer" - } - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php webRequest docs/assets/sarif 192` -See full [`examples/webRequest.php`][example-script] script into repository. + ```json title="docs/assets/sarif/webRequest.json" + --8<-- "docs/assets/sarif/webRequest.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/webRequest.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/webRequest.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/webRequest.php + ```php title="examples/webRequest.php" + --8<-- "examples/webRequest.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$tool = new Tool($driver); - -$webRequest = new WebRequest(); -$webRequest->setProtocol('http'); -$webRequest->setVersion('1.1'); -$webRequest->setMethod('GET'); -$webRequest->setTarget('httpbin.org/bearer'); -$webRequest->addAdditionalPropertiesHeaders([ - 'accept' => 'application/json', - 'Authorization' => 'none', -]); - -$run = new Run($tool); -$run->addWebRequests([$webRequest]); - -``` + ```php title="examples/builder/webRequest.php" + --8<-- "examples/builder/webRequest.php" + ``` diff --git a/docs/reference/webResponse.md b/docs/reference/webResponse.md index b47fd3f..300173a 100644 --- a/docs/reference/webResponse.md +++ b/docs/reference/webResponse.md @@ -3,96 +3,31 @@ A `webResponse` object describes the response to an HTTP request (RFC7230) -![webResponse object](../assets/images/reference-web-response.graphviz.svg) +=== ":simple-uml: Graph" -## Example + ![webResponse object](../assets/images/reference-web-response.graphviz.svg) -```json -{ - "$schema": "https://json.schemastore.org/sarif-2.1.0.json", - "version": "2.1.0", - "runs": [ - { - "tool": { - "driver": { - "name": "CodeScanner", - "semanticVersion": "1.1.2-beta.12", - "informationUri": "https://codeScanner.dev" - } - }, - "webRequests": [ - { - "protocol": "http", - "version": "1.1", - "target": "httpbin.org/bearer", - "method": "GET", - "headers": { - "accept": "application/json", - "Authorization": "none" - } - } - ], - "webResponses": [ - { - "protocol": "http", - "version": "1.1", - "statusCode": 401, - "reasonPhrase": "Error: UNAUTHORIZED", - "headers": { - "access-control-allow-credentials": "true", - "access-control-allow-origin": "*", - "connection": "keep-alive", - "content-length": "0", - "content-type": "text/html; charset=utf-8", - "date": "Sun, 07 Nov 2021 08:59:53 GMT", - "server": "gunicorn/19.9.0", - "www-authenticate": "Bearer" - } - } - ], - "results": [] - } - ] -} -``` +=== ":octicons-file-code-16: sarif.json" -## How to generate + > [!TIP] + > + > Generated with following command : `php ./resources/serialize.php webRequest docs/assets/sarif 192` -See full [`examples/webRequest.php`][example-script] script into repository. + ```json title="docs/assets/sarif/webRequest.json" + --8<-- "docs/assets/sarif/webRequest.json" + ``` -> [!NOTE] -> Since release 1.5.0, you may use fluent builders API as alternative. -> See full [`examples/builder/webRequest.php`][example-builder] script into repository. +=== ":simple-php: Simple API" -[example-script]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/webRequest.php -[example-builder]: https://github.com/llaville/sarif-php-sdk/blob/master/examples/builder/webRequest.php + ```php title="examples/webRequest.php" + --8<-- "examples/webRequest.php" + ``` -```php - [!NOTE] + > This alternative API is available since release 1.5.0 -$tool = new Tool($driver); - -$webResponse = new WebResponse(); -$webResponse->setProtocol('http'); -$webResponse->setVersion('1.1'); -$webResponse->setStatusCode(401); -$webResponse->setReasonPhrase('Error: UNAUTHORIZED'); -$webResponse->addAdditionalProperties([ - 'access-control-allow-credentials' => 'true', - 'access-control-allow-origin' => '*', - 'connection' => 'keep-alive', - 'content-length' => '0', - 'content-type' => 'text/html; charset=utf-8', - 'date' => 'Sun, 07 Nov 2021 08:59:53 GMT', - 'server' => 'gunicorn/19.9.0', - 'www-authenticate' => 'Bearer', -]); - -$run = new Run($tool); -$run->addWebResponses([$webResponse]); - -``` + ```php title="examples/builder/webRequest.php" + --8<-- "examples/builder/webRequest.php" + ``` diff --git a/mkdocs.yml b/mkdocs.yml index 3b608a9..45f3d79 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -23,6 +23,28 @@ theme: - navigation.tabs # Navigation tabs -- https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#navigation-tabs - navigation.indexes # Section index pages -- https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages - navigation.top # Back-To-Top button -- https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#back-to-top-button + - navigation.footer # Setting up the footer -- https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/ + - content.code.copy # Code copy button -- https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-copy-button + - content.code.annotate # Code blocks, Adding annotations -- https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-annotations markdown_extensions: - - pymdownx.highlight # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight - - pymdownx.superfences # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences + - attr_list + - md_in_html # https://squidfunk.github.io/mkdocs-material/reference/grids/ + - tables # https://squidfunk.github.io/mkdocs-material/reference/data-tables/ + - footnotes # https://squidfunk.github.io/mkdocs-material/reference/footnotes/ + - pymdownx.highlight: # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#highlight + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: # https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#content-tabs + alternate_style: true + - pymdownx.superfences: # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.emoji: # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#emoji + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg +# - github-callouts diff --git a/resources/gh-pages-hook.sh b/resources/gh-pages-hook.sh index 8f6c327..d91f3aa 100755 --- a/resources/gh-pages-hook.sh +++ b/resources/gh-pages-hook.sh @@ -53,3 +53,44 @@ php $SCRIPT_DIR/build.php reference-translation-metadata $ASSETS_IMAGE_DIR php $SCRIPT_DIR/build.php reference-version-control-details $ASSETS_IMAGE_DIR php $SCRIPT_DIR/build.php reference-web-request $ASSETS_IMAGE_DIR php $SCRIPT_DIR/build.php reference-web-response $ASSETS_IMAGE_DIR + +ASSETS_JSON_DIR="docs/assets/sarif" + +JSON_ENCODE_FLAGS=192 # (pretty print: 128, unescaped slashes: 64) + +php $SCRIPT_DIR/serialize.php message/embeddedLinks $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php message/formatted $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php message/plainText $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php message/stringLookup $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php address $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php artifact $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php attachment $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php codeFlow $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php configurationOverride $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php conversion $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php exception $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php externalProperties $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php externalPropertyFileReferences $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php fix $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php graph $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php graphTraversal $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php locationRelationship $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php logicalLocation $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php physicalLocation $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php rectangle $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php reportingConfiguration $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php reportingDescriptor $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php reportingDescriptorReference $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php reportingDescriptorRelationship $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php result $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php resultProvenance $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php run $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php runAutomationDetails $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php sarifLog $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php specialLocations $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php stack $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php suppression $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php tool $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php translationMetadata $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php versionControlDetails $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS +php $SCRIPT_DIR/serialize.php webRequest $ASSETS_JSON_DIR $JSON_ENCODE_FLAGS