PSRAFSCAN DOCUMENTATION

Create Rules and Rule Self-Tests

Use the included templates to create custom PSRafScan rules, positive and negative self-tests, expected findings, and validation checks.

Test every rule

A rule file defines searchable metadata and evaluation behavior. A self-test defines the source fixture, intended use, threshold, expected result, findings that must appear, and findings that must stay absent.

Start from the templates

Use the repository's Rule and Test Authoring Guide for the complete file contract.

src/PSRafScan/Templates/RuleTemplate.ps1
src/PSRafScan/Templates/SelfTestTemplate.psd1

Create the rule file

Match the filename to RuleName. Write direct Issue and Fix text, and choose Pattern, Token, Ast, or Hybrid for the evaluation style.

src/PSRafScan/Rules/CustomRules/<RuleName>.rule.ps1
@{
    SchemaVersion = '1.0'
    RuleName = 'ExampleRuleName'
    DisplayName = 'Example Rule Name'
    Category = 'Safety'
    RuleType = 'Ast'
    Severity = 'Warning'
    Enabled = $true
    IntendedUse = @('TerminalPaste', 'Ps1File')
    Tags = @('safety', 'example')
    Description = 'Detects Example-Command calls.'
    Issue = 'The script calls Example-Command.'
    Fix = 'Replace Example-Command with the approved command.'
    Version = '1.0.0'
    Author = 'PSRafScan'
    Aliases = @()
    Deprecated = $false
    DeprecatedSince = $null
}

Create positive and negative self-tests

  • A positive fixture should trigger the exact rule and severity.
  • A negative fixture should resemble the trigger while remaining allowed.
  • ExpectedFindings lists findings that must appear.
  • NotExpectedFindings protects against likely false positives.
src/PSRafScan/SelfTests/Cases/<TestName>/Script.ps1
src/PSRafScan/SelfTests/Cases/<TestName>/<TestName>.expected.psd1

Run validation checks

Confirm the catalog can find the rule, the positive case triggers, negative cases stay quiet, metadata references remain current, and the full self-test suite still passes.

Get-PSRafScanRule -RuleName ExampleRuleName
Get-PSRafScanSelfTest -RuleName ExampleRuleName
RSX -SelfTest
pwsh -ExecutionPolicy Bypass -File ./tools/Test-PSRafScanMetadataCatalog.ps1
pwsh -ExecutionPolicy Bypass -File ./tools/Test-PSRafScanQualityGate.ps1

Manage the rule lifecycle

  • Set Enabled = $false to omit a rule from scans and default listings.
  • Set Deprecated = $true and record DeprecatedSince when replacing a rule.
  • When deleting a rule, update every self-test reference to it.
  • Update the rule and its self-tests together.