AzureDevOpsPipeline.psm1
|
# Module Constants #Set-Variable XYZ -option Constant -value (@{XYZ = 'abc'}) Function Get-TrivyCommand { <# .SYNOPSIS Get a Command to run trivy .EXAMPLE & (Get-TrivyCommand) fs . #> [CmdletBinding()] [OutputType([PSCustomObject])] param() Process { if(-not (Test-Trivy)) { throw "Install-Trivy must be called prior to this function." } # Retrieve trivy command $trivy = Get-Command "$($env:TrivyPath)" -ErrorAction SilentlyContinue if(-not ($trivy -is [System.Management.Automation.ApplicationInfo])) { throw "Unable to Get Command `$($env:TrivyPath)`." } $trivy | Write-Output } } Function Get-TrivyPackageInformation { <# .SYNOPSIS Get trivy package information .EXAMPLE $PackageInformation = Get-TrivyPackageInformation #> [CmdletBinding(DefaultParameterSetName = 'AutoDetect')] [OutputType([PSCustomObject])] param( [Parameter(Mandatory = $false, ParameterSetName = 'AutoDetect')] [switch] $AutoDetect, [Parameter(Mandatory = $true, ParameterSetName = 'Windows')] [switch] $Windows, [Parameter(Mandatory = $true, ParameterSetName = 'Linux')] [switch] $Linux ) Begin { $PackageInformation = [pscustomobject]@{ releaseInfoUri = 'https://api.github.com/repos/aquasecurity/trivy/releases/latest' releaseContentType = 'application/vnd.github.v3+json' data = $null outdir = $null path = $null bin = $null binpath = $null archiveExpression = $null downloadUri = $null releaseInfo = $null version = $null windows = $false linux = $false } } Process { $Target = $null if ($PSCmdlet.ParameterSetName -eq 'AutoDetect') { if (Test-IsWindows) { $Target = 'Windows' } else { $Target = 'Linux' } } else { if ($Windows.IsPresent -and $Windows) { $Target = 'Windows' } elseif ($Linux.IsPresent -and $Linux) { $Target = 'Linux' } } if ($null -eq $Target) { throw "Unable to determine target platform" } else { $PackageInformation.linux = ($Target -eq 'Linux') $PackageInformation.windows = ($Target -eq 'Windows') } if ($PackageInformation.windows) { $PackageInformation.archiveExpression = '^trivy_([\d\.]+)_Windows-64bit.zip$' $PackageInformation.path = 'C:\Program Files\trivy' $PackageInformation.bin = 'trivy.exe' $PackageInformation.binpath = Join-Path $PackageInformation.path $PackageInformation.bin $PackageInformation.data = Join-Path $env:LocalAppData 'trivy/db' $PackageInformation.outdir = Join-Path $env:LocalAppData 'trivy/out' } else { $PackageInformation.archiveExpression = '^trivy_([\d\.]+)_Linux-64bit.tar.gz$' $PackageInformation.path = '/usr/local/bin/trivy' $PackageInformation.bin = 'trivy' $PackageInformation.binpath = Join-Path $PackageInformation.path $PackageInformation.bin $PackageInformation.data = '/usr/local/bin/trivy/db' $PackageInformation.outdir = '/tmp/trivy-out' } # Get the Release Information, and Download URI "Invoke-RestMethod -Uri $($PackageInformation.releaseInfoUri) -Headers @{Accept = $($PackageInformation.releaseContentType) }" | Write-Debug $PackageInformation.releaseInfo = Invoke-RestMethod -Uri $PackageInformation.releaseInfoUri -Headers @{Accept = $PackageInformation.releaseContentType } | Select-Object -ExpandProperty assets | Where-Object { $_.name -match $PackageInformation.archiveExpression } # Update the download URI, Package, and Version $PackageInformation.downloadUri = $PackageInformation.releaseInfo | Select-Object -ExpandProperty browser_download_url $PackageInformation.releaseInfo.name -match $PackageInformation.archiveExpression | Out-Null $PackageInformation.version = $matches[1] if (-Not $PackageInformation.downloadUri) { throw 'Unable to retrieve the download URI.' } "Package: $($PackageInformation.releaseInfo.name) ($($PackageInformation.version)) - [Download]($($PackageInformation.downloadUri))" | Write-Verbose # Output the Trivy Package Information $PackageInformation | Write-Output } } Function Out-Task { <# .SYNOPSIS Write to the pipeline's task output .EXAMPLE "Hello World" | Out-Task .EXAMPLE "Hello World" | Out-Task -Prefix '##[command]' .EXAMPLE "Hello World" | Out-Task -Prefix '##vso[task.logissue type=error]' .EXAMPLE "Hello World" | Out-Task -VsoCommand 'task.logissue' -VsoProperties @{type='error'} #> [CmdletBinding(DefaultParameterSetName = 'prefix')] param( [Parameter(Mandatory = $false, ValueFromPipeline = $true)] [AllowNull()] [AllowEmptyCollection()] [Object] $Message, [Parameter(Mandatory = $false, ParameterSetName = 'prefix')] [AllowEmptyString()] [AllowNull()] [String] $Prefix = '', [Parameter(Mandatory = $true, ParameterSetName = 'vso')] [String] $VsoCommand, [Parameter(Mandatory = $false, ParameterSetName = 'vso')] [AllowNull()] [hashtable] $VsoProperties ) Process { if($PSCmdlet.ParameterSetName -eq 'vso') { if ($VsoProperties -eq $null -or $VsoProperties.Count -eq 0) { $Prefix = "##vso[$VsoCommand]" } else { $VsoPropertiesArray = $VsoProperties.GetEnumerator() | ForEach-Object { "$($_.Key)=$($_.Value)" } $VsoPropertiesString = $VsoPropertiesArray -join ';' $Prefix = "##vso[$VsoCommand $VsoPropertiesString;]" } } $Message | Out-String -Stream | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Text.Encoding]::UTF8.GetBytes("$($Prefix)$($_)")) | Write-Host } } } Function Test-IsAdministrator { <# .SYNOPSIS Test if current user has Administrator privileges .EXAMPLE if(-not (Test-IsAdministrator)) { throw 'Not an admin.' } #> [CmdletBinding()] [OutputType([PSCustomObject])] param() Process { return (New-Object Security.Principal.WindowsPrincipal -ArgumentList ([Security.Principal.WindowsIdentity]::GetCurrent())).IsInRole( [Security.Principal.WindowsBuiltInRole]::Administrator ) } } Function Get-TrivyOutputDirectory { <# .SYNOPSIS Get the OutputDirectory used by Trivy .EXAMPLE # Get the directory where reports are saved Get-TrivyOutputDirectory | Out-TaskLog -Format 'Debug' .EXAMPLE # Get the staging directory where other files are saved (this is Azure DevOps' BUILD_ARTIFACTSTAGINGDIRECTORY directory) Get-TrivyOutputDirectory -Staging | Out-TaskLog -Format 'Debug' #> [CmdletBinding()] [OutputType([PSCustomObject])] param( [Parameter(Mandatory = $false)] [Switch] $Staging ) Process { if(Test-Trivy) { if($Staging) { return $env:BUILD_ARTIFACTSTAGINGDIRECTORY } return $env:TrivyOutPath } } } Function Install-Trivy { <# .SYNOPSIS Download and Install trivy on the CI/CD host .EXAMPLE Install-Trivy #> [CmdletBinding()] [OutputType([PSCustomObject])] param() Process { # Check for Administrator role # ----------------------------- "Testing Administrator role" | Out-TaskLog if (-Not (Test-IsAdministrator)) { "Insufficient privileges" | Write-TaskError } # Initialization # ----------------------------- "Initializing" | Out-TaskLog -Format 'BeginGroup' # Get the download package information $PackageInformation = Get-TrivyPackageInformation -AutoDetect # DEBUG: Print all elements in $PackageInformation "Package Information" | Out-TaskLog -Format 'Section' $PackageInformation.PSObject.Properties | ForEach-Object { "- $($_.Name) = $($_.Value)" | Out-TaskLog -Format 'Debug' } # Create Directories "Creating directories" | Out-TaskLog -Format 'Section' @($PackageInformation.path, $PackageInformation.outdir) | ForEach-Object { if (-Not (Test-Path $_)) { "New-Item -ItemType Directory -Path $_" | Out-TaskLog -Format 'Command' New-Item -ItemType Directory -Path $_ -Force | Out-Null } } # Done "Done" | Out-TaskLog -Format 'EndGroup' # Installation # ----------------------------- "Installing" | Out-TaskLog -Format 'BeginGroup' # Download Trivy "Downloading $($PackageInformation.releaseInfo.name)" | Out-TaskLog "Invoke-WebRequest -Uri $($PackageInformation.downloadUri) -OutFile $($PackageInformation.releaseInfo.name)" | Out-TaskLog -Format 'Command' Invoke-WebRequest -Uri $PackageInformation.downloadUri -OutFile $PackageInformation.releaseInfo.name | Out-TaskLog # Inflate downloaded archive, and add to PATH "Expanding $($PackageInformation.releaseInfo.name) to $($PackageInformation.path)" | Out-TaskLog if ((Test-IsWindows)) { "Expand-Archive -LiteralPath $($PackageInformation.releaseInfo.name) -DestinationPath $($PackageInformation.path) -Force" | Out-TaskLog -Format 'Command' Expand-Archive -LiteralPath "$($PackageInformation.releaseInfo.name)" -DestinationPath $PackageInformation.path -Force | Out-TaskLog } else { "tar -zxvf $($PackageInformation.releaseInfo.name) -C $($PackageInformation.path)" | Out-TaskLog -Format 'Command' tar -zxvf $PackageInformation.releaseInfo.name -C $PackageInformation.path | Out-TaskLog "chmod u+x $((Join-Path $PackageInformation.Path $PackageInformation.bin))" | Out-TaskLog -Format 'Command' chmod u+x (Join-Path $PackageInformation.Path $PackageInformation.bin) | Out-TaskLog } # Adding trivy to the PATH New-TaskPathVariable -Path $PackageInformation.Path # Delete downloaded archive "Remove-Item -Path $($PackageInformation.releaseInfo.name)" | Out-TaskLog -Format 'Command' Remove-Item -Path $PackageInformation.releaseInfo.name -ErrorAction SilentlyContinue | Out-Null # Set variables into the pipeline "Updating environment..." | Out-TaskLog "`$(TrivyPath) = $($PackageInformation.binpath)" | Out-TaskLog -Format 'Debug' New-TaskVariable -Name 'TrivyPath' -Value ($PackageInformation.binpath) "`$(TrivyDbPath) = $($PackageInformation.data)" | Out-TaskLog -Format 'Debug' New-TaskVariable -Name 'TrivyDbPath' -Value ($PackageInformation.data) "`$(TrivyVersion) = $($PackageInformation.version)" | Out-TaskLog -Format 'Debug' New-TaskVariable -Name 'TrivyVersion' -Value ($PackageInformation.version) "`$(TrivyOutPath) = $($PackageInformation.outdir)" | Out-TaskLog -Format 'Debug' New-TaskVariable -Name 'TrivyOutPath' -Value ($PackageInformation.outdir) # Done "Done" | Out-TaskLog -Format 'EndGroup' # Get the trivy command # ----------------------------- "Get-Command $($PackageInformation.binpath)" | Out-TaskLog -Format 'Command' $TrivyCommand = Get-Command $PackageInformation.binpath -ErrorAction SilentlyContinue if (-not ($TrivyCommand -is [System.Management.Automation.ApplicationInfo])) { throw "Unable to get Command $trivyPath." } # Download Trivy Database # ----------------------------- "Downloading vulnerability database" | Out-TaskLog -Format 'BeginGroup' "trivy image --download-db-only --cache-dir ""$($PackageInformation.data)""" | Out-TaskLog -Format 'Command' & ($TrivyCommand) image --download-db-only --cache-dir "$($PackageInformation.data)" 2>&1 | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] } | Out-TaskLog if ($LASTEXITCODE -ne 0) { throw "Trivy reported an error. Exit Code: $LASTEXITCODE" } # Done "Done" | Out-TaskLog -Format 'EndGroup' } } Function Invoke-Trivy { <# .SYNOPSIS Download and Install trivy on the CI/CD host .PARAMETER InputDirectory The input directory to scan .PARAMETER Name A nickname for the reports (useful if you generate multiple reports) .EXAMPLE Invoke-Trivy -InputDirectory . #> [CmdletBinding()] [OutputType([PSCustomObject])] param( [Parameter(Mandatory = $false)] [ValidateScript({Test-Path $_ -PathType Container})] $InputDirectory = '.', [Parameter(Mandatory = $false)] $Name = 'report' ) Process { # Retrieve the trivy Command $trivy = Get-TrivyCommand # Run trivy on the target directory, capturing all dependencies, store JSON result in the BUILD_ARTIFACTSTAGINGDIRECTORY $DependenciesPath = Join-Path $env:BUILD_ARTIFACTSTAGINGDIRECTORY "dependency-$($Name).json" $SecurityReportPath = Join-Path $env:TrivyOutPath "sast-$($Name).sarif" # Scan and list dependencies "Running Static application security testing (trivy $($env:TrivyVersion))" | Out-TaskLog -Format 'BeginGroup' "Scanning $($InputDirectory)" | Out-TaskLog -Format 'Section' "trivy fs $($InputDirectory) --skip-db-update --cache-dir ""$($env:TrivyDbPath)"" --list-all-pkgs --format json --output ""$($DependenciesPath)""" | Out-TaskLog -Format 'Command' & ($trivy) fs "$($InputDirectory)" --skip-db-update --cache-dir "$($env:TrivyDbPath)" --list-all-pkgs --format json --output "$($DependenciesPath)" 2>&1 | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] } | Out-String | Out-TaskLog if($LASTEXITCODE -ne 0) { throw "Trivy reported an error. Exit Code: $LASTEXITCODE" } # Testing if the file exists if(Test-Path -Path $DependenciesPath) { $DependenciesPath | Out-TaskLog -Format Debug New-TaskLogUpload -Path $DependenciesPath } else { throw "Trivy did not generate a JSON file." } # Generate SARIF report from the Scan "Converting JSON to SARIF" | Out-TaskLog -Format 'Section' "trivy convert --format sarif --output ""$($SecurityReportPath)"" ""$($DependenciesPath)""" | Out-TaskLog -Format 'Command' & ($trivy) convert --format sarif --output "$($SecurityReportPath)" "$($DependenciesPath)" 2>&1 | Where-Object { $_ -is [System.Management.Automation.ErrorRecord] } | Out-String | Out-TaskLog if($LASTEXITCODE -ne 0) { throw "Trivy reported an error. Exit Code: $LASTEXITCODE" } # Testing if the file exists if(Test-Path -Path $SecurityReportPath) { $SecurityReportPath | Out-TaskLog -Format Debug New-TaskLogUpload -Path $SecurityReportPath } else { throw "Trivy did not generate a SARIF file." } # Done "Done" | Out-TaskLog -Format 'EndGroup' } } Function New-TaskLogUpload { <# .SYNOPSIS Upload a file to the Task Log .EXAMPLE "C:\my\directory\file.txt" | New-TaskLogUpload #> [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [ValidateScript({Test-Path $_ -PathType 'Leaf'})] [string] $Path ) Begin { } Process { $Path | Out-Task -VsoCommand 'task.uploadfile' } } Function New-TaskPathVariable { <# .SYNOPSIS Add an entry to the environment's path (prepend) .EXAMPLE "C:\my\directory\path" | New-TaskPathVariable #> [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [string] $Path ) Begin { } Process { $Path | Out-Task -VsoCommand 'task.prependpath' # Alternatives # # # For windows: # #$Path = [System.Environment]::GetEnvironmentVariable("Path", [System.EnvironmentVariableTarget]::Machine) -split ';' # #$Path += , ($Trivy.Path) # #[System.Environment]::SetEnvironmentVariable("Path", ($Path | Select-Object -Unique) -join ';', [System.EnvironmentVariableTarget]::Machine) # # # For linux: # #"export PATH=`$PATH:""$($Trivy.path)""" | Out-File -Append -Encoding utf8 ~/.bashrc # #bash -c ". ~/.bashrc" } } Function New-TaskSecret { <# .SYNOPSIS Create an environment variable in the pipeline .EXAMPLE "Hello World" | New-TaskVariable -Name 'MESSAGE' #> [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [string] $Secret ) Begin { } Process { $Secret | Out-Task -VsoCommand 'task.setsecret' } } Function New-TaskVariable { <# .SYNOPSIS Create an environment variable in the pipeline .EXAMPLE "Hello World" | New-TaskVariable -Name 'MESSAGE' #> [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [string] $Value, [Parameter(Mandatory = $true)] [string] $Name, [Parameter(Mandatory = $false)] [switch] $IsSecret, [Parameter(Mandatory = $false)] [string] $IsOutput, [Parameter(Mandatory = $false)] [string] $IsReadOnly ) Begin { } Process { $Properties = @{ variable = $Name } if($IsSecret) { $Properties += @{isSecret='true'} } if($IsOutput) { $Properties += @{isOutput='true'} } if($IsReadOnly) { $Properties += @{isReadOnly='true'} } $Value | Out-Task -VsoCommand 'task.setvariable' -VsoProperties $Properties } } Function Out-TaskLog { <# .SYNOPSIS Write to the pipeline's task output .EXAMPLE "Hello World" | Out-TaskLog -Format 'None' #> [CmdletBinding()] param( [Parameter(Mandatory = $false, ValueFromPipeline = $true)] [AllowNull()] [AllowEmptyString()] [string] $Message = '', [Parameter(Mandatory = $false)] [ValidateSet('None', 'BeginGroup', 'Warning', 'Error', 'Section', 'Debug', 'Command', 'EndGroup')] [string] $Format = 'None' ) Begin { } Process { $Prefix = switch($Format.ToLower()) { 'begingroup' { '##[group]' } 'warning' { '##[warning]' } 'error' { '##[error]' } 'section' { '##[section]' } 'debug' { '##[debug]' } 'command' { '##[command]' } 'endgroup' { '##[endgroup]' } default { $null } } $Message | Out-Task -Prefix $Prefix } } Function Set-TaskLogProgress { <# .SYNOPSIS Set progress and current operation for the current task. .EXAMPLE 'Downloading' | Set-TaskLogProgress -PercentComplete 50 #> [CmdletBinding()] param( [Parameter(Mandatory = $false, ValueFromPipeline = $true)] [AllowEmptyString()] [AllowNull()] [string] $Message, [Parameter(Mandatory = $true)] [ValidateRange(0, 100)] [int] $PercentComplete ) Begin { } Process { $Message | Out-Task -VsoCommand 'task.setprogress' -VsoProperties @{ value = $PercentComplete.ToString() } } } Function Set-TaskResult { <# .SYNOPSIS Finish the timeline record for the current task, set task result and current operation. .EXAMPLE 'DONE' | Set-TaskResult -Result 'Succeeded' #> [CmdletBinding()] param( [Parameter(Mandatory = $false, ValueFromPipeline = $true)] [AllowEmptyString()] [AllowNull()] [string] $Message = 'Done', [Parameter(Mandatory = $false)] [ValidateSet('Succeeded', 'SucceededWithIssues', 'Failed')] [string] $Result = 'Succeeded' ) Begin { } Process { $Properties = @{ 'result' = $Result } $Message | Out-Task -VsoCommand 'task.complete' -VsoProperties $Properties } } Function Test-IsWindows { <# .SYNOPSIS Test if current operating system is Windows .EXAMPLE if(-not (Test-IsWindows)) { throw "Not a windows OS" } #> [CmdletBinding()] [OutputType([PSCustomObject])] param() Process { if($IsWindows) { # Powershell Core return $true } if(($PSVersionTable.Platform) -eq 'Win32NT') { # Powershell 6 Core return $true } if(([System.Environment]::OSVersion.Platform) -eq 'Win32NT') { # .Net 1.1, 2.0, 3.0, 3.5, ... return $true } if((Test-Path env:OS) -and $env:OS -eq 'Windows_NT') { # Windows Environment Variable return $true } return $false } } Function Test-Trivy { <# .SYNOPSIS Test installation of trivy .EXAMPLE if(-not (Test-Trivy)) { throw "Please call Install-Trivy" } #> [CmdletBinding()] [OutputType([PSCustomObject])] param() Process { try { if(-not (Test-Path env:SYSTEM_ISAZUREVM)) { throw "Environment variable SYSTEM_ISAZUREVM is missing. This function is designed to be called from within a Azure DevOps pipeline Did you call Install-Trivy?" } if(-not (Test-Path env:BUILD_ARTIFACTSTAGINGDIRECTORY)) { throw "Environment variable BUILD_ARTIFACTSTAGINGDIRECTORY is missing. This function is designed to be called from within a Azure DevOps pipeline Did you call Install-Trivy?" } if(-not (Test-Path env:TrivyPath)) { throw "Environment variable TrivyPath is missing. Did you call Install-Trivy?" } if(-not (Test-Path env:TrivyDbPath)) { throw "Environment variable TrivyDbPath is missing. Did you call Install-Trivy?" } if(-not (Test-Path env:TrivyOutPath)) { throw "Environment variable TrivyOutPath is missing. Did you call Install-Trivy?" } return $true } catch { $_ | Write-TaskWarning } return $false } } Function Write-TaskError { <# .SYNOPSIS Write an error to the pipeline's task output .EXAMPLE "Hello World" | Write-TaskError .EXAMPLE "Hello World" | Write-TaskError -SourcePath 'C:\path\to\file.txt' -SourceLine 1 -SourceColumn 1 -Code 'E0001' #> [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [string] $Message, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $SourcePath, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $SourceLine, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $SourceColumn, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $Code ) Begin { } Process { $Properties = @{ type = 'error' } if($SourcePath) { $Properties += @{sourcepath=$SourcePath} } if($SourceLine) { $Properties += @{linenumber=$SourceLine} } if($SourceColumn) { $Properties += @{columnnumber=$SourceColumn} } if($Code) { $Properties += @{code=$Code} } $Message | Out-String -Stream | ForEach-Object { $_ | Out-Task -VsoCommand 'task.logissue' -VsoProperties $Properties } } } Function Write-TaskWarning { <# .SYNOPSIS Write a warning to the pipeline's task output .EXAMPLE "Hello World" | Write-TaskWarning .EXAMPLE "Hello World" | Write-TaskWarning -SourcePath 'C:\path\to\file.txt' -SourceLine 1 -SourceColumn 1 -Code 'E0001' #> [CmdletBinding()] param( [Parameter(Mandatory = $true, ValueFromPipeline = $true)] [string] $Message, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $SourcePath, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $SourceLine, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $SourceColumn, [Parameter(Mandatory = $false)] [AllowNull()] [AllowEmptyString()] [string] $Code ) Begin { } Process { $Properties = @{ type = 'warning' } if($SourcePath) { $Properties += @{sourcepath=$SourcePath} } if($SourceLine) { $Properties += @{linenumber=$SourceLine} } if($SourceColumn) { $Properties += @{columnnumber=$SourceColumn} } if($Code) { $Properties += @{code=$Code} } $Message | Out-String -Stream | ForEach-Object { $_ | Out-Task -VsoCommand 'task.logissue' -VsoProperties $Properties } } } |