microsoft / converttosarif

A tool to transform PSScriptAnalyzer output to the SARIF format

ConvertToSARIF

This is a simple utility PSCmdlet used to convert the output of the PSScriptAnalyzer to the SARIF format using pipelines.

Download

The tool is available for download from the PowerShell Gallery here.

Getting Started

To run the program you have to call the Invoke-ScriptAnalyzer and then pipeline it to the ConvertTo-SARIF:

Invoke-ScriptAnalyzer .\scripts\ -Recurse | ConvertTo-SARIF -FilePath results.sarif

ConvertToSARIF has a single required parameter FilePath, which is relative to the current directory of Powershell.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

converttosarif's Issues

Missing version for driver

Schema expects a version and/or semanticversion in runs/tool/driver. Since PSScriptAnalyzer isn't required in this module, then maybe hardcode version of ConverToSARIF for now?

Add parameters for versionControlProvenance and use relative paths

To enable deeplinks to repo source in tools like https://marketplace.visualstudio.com/items?itemName=sariftools.scans (and https://github.com/microsoft/sarif-web-component which it wraps) we need at least:

• versionControlProvenance-node with repositoryUri and revisionId (commit)
• Relative paths without file:// (AFAIK) and possibly adding uriBaseId and originalUriBaseIds to define root

A sample for reference here though it's way more complicated than we need here. 🙂

I've gotten a manual sample working like this:

{
    "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
    "version": "2.1.0",
    "runs": [
        {
            "tool": {
                "driver": {
                    "name": "PSScriptAnalyzer",
                    "version": "1.0.0",
                    "informationUri": "https://github.com/PowerShell/PSScriptAnalyzer",
                    "rules": [
                        {
                            "id": "rule-PSAvoidUsingWriteHost",
                            "name": "PSAvoidUsingWriteHost",
                            "helpUri": "https://github.com/PowerShell/Psscriptanalyzer"
                        },
                        {
                            "id": "rule-PSAvoidTrailingWhitespace",
                            "name": "PSAvoidTrailingWhitespace",
                            "helpUri": "https://github.com/PowerShell/Psscriptanalyzer"
                        }
                    ]
                }
            },
            "originalUriBaseIds": {
                "SRCROOT": {
                    "uri": "file:///C:/Git/sandboxrepo/"
                }
            },
            "artifacts": [
                {
                    "location": {
                        "uri": "demo.tests.ps1",
                        "uriBaseId": "SRCROOT"
                    }
                },
                {
                    "location": {
                        "uri": "subfolder/demo.testsv4.ps1",
                        "uriBaseId": "SRCROOT"
                    }
                }
            ],
            "results": [
                {
                    "ruleId": "PSAvoidUsingWriteHost",
                    "message": {
                        "text": "File 'demo.tests.ps1' uses Write-Host. Avoid using Write-Host because it might not work in all hosts, does not work when there is no host, and (prior to PS 5.0) cannot be suppressed, captured, or redirected. Instead, use Write-Output, Write-Verbose, or Write-Information."
                    },
                    "locations": [
                        {
                            "physicalLocation": {
                                "artifactLocation": {
                                    "uri": "demo.tests.ps1",
                                    "uriBaseId": "SRCROOT"
                                },
                                "region": {
                                    "startLine": 23,
                                    "startColumn": 13
                                }
                            }
                        }
                    ]
                },
                {
                    "ruleId": "PSAvoidTrailingWhitespace",
                    "level": "note",
                    "message": {
                        "text": "Line has trailing whitespace"
                    },
                    "locations": [
                        {
                            "physicalLocation": {
                                "artifactLocation": {
                                    "uri": "subfolder/demo.testsv4.ps1",
                                    "uriBaseId": "SRCROOT"
                                },
                                "region": {
                                    "startLine": 10,
                                    "startColumn": 1
                                }
                            }
                        }
                    ]
                }
            ],
            "columnKind": "utf16CodeUnits",
            "versionControlProvenance": [
                {
                    "repositoryUri": "https://dev.azure.com/myorg/myproject/_git/sandboxrepo",
                    "revisionId": "commmithash"
                }
            ]
        }
    ]
}

Rules should not have equal name and id

name (friendly name) is optional for rules in SARIF schema and causes an error in SARIF Validator when it's equal to id which is mandatory. Since PSSA only provide RuleName then this should only populate id OR prefix id with ex. 'rule-`?

Mandatory FilePath parameter is against PowerShell philosophy

Currently the FilePath parameter is mandatory which does not really follow the PowerShell way of doing things.
I want to update the file paths with urls but the way the CommandLet works right now is making it very clumsy.

How it works now which is ugly.

function Set-SARIFCodePath {
    param(
        [string] $SarifFile,
        [string] $GitRoot,
        [string] $GitRemote
    )
    $content = Get-Content -Path $SarifFile
    $updatedContent = $content -replace "file:///$GitRoot", "$GitRemote`?path="
    $updatedContent | Set-Content -Path $SarifFile
}

$gitRoot = git rev-parse --show-toplevel
$gitRemote = git config --get remote.origin.url

Invoke-ScriptAnalyzer -Path $Path -Recurse -ReportSummary | ConvertTo-SARIF -FilePath $ResultsFilepath
Set-SARIFCodePath -SarifFile $ResultsFilepath -GitRoot $gitRoot -GitRemote $gitRemote

How it should work:

function Set-SARIFCodePath {
    param(
        [Parameter(ValueFromPipeline = $true)]
        [string] $SarifContent,
        [string] $GitRoot,
        [string] $GitRemote
    )
    $SarifContent -replace "file:///$GitRoot", "$GitRemote`?path="
}

$gitRoot = git rev-parse --show-toplevel
$gitRemote = git config --get remote.origin.url

Invoke-ScriptAnalyzer -Path $Path -Recurse -ReportSummary | `
     ConvertTo-SARIF | `
     Set-SARIFCodePath -GitRoot $gitRoot -GitRemote $gitRemote | `
     Out-File -FilePath analysisfindings.sarif

I can make the change, but I want confirmation that this is a good approach first.

Project maintenance

I noticed that the last commit was 13 months ago and that the issues and pull request are not being commented. Could someone in Microsoft take ownership of this project so that bugfixes and feature requests can be handled.

I will happily contribute the code changes, but only when we can discuss the approach and get the changes merged into the project. We have a ton of PowerShell in our company and converting to SARIF allows us to publish the results in the Azure DevOps pipelines.

Add startColumn to location region

Add Column from PSSA output as startColumn in region for more precise deeplinks

Use of outdated SARIF-schema

Generated SARIF-file doesn't pass SARIF Validator due to use of old schema.

Should use latest official spec: https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json

Rule help

Can the rule help documentation or URI be added to the alert? Here is an example a rule.