How PSRafScan Reviews PowerShell Scripts
See how PSRafScan combines native PowerShell parsing, its own static rules, intended-use context, reports, and thresholds without intentionally executing the target.
Direct answer
1. Resolve the review input
A direct scan accepts an existing file through -Path or text already present on the clipboard through -Clipboard. It does not expose a public raw-string input.
Clipboard text is currently written to a temporary .ps1 file under a PSRafScan working directory before parsing. Current source does not prove automatic cleanup, so do not describe that file as automatically deleted.
2. Let the native parser inspect the file
PowerShell's parser returns tokens, parse errors, and an abstract syntax tree. PSRafScan normalizes parser errors as PowerShellParseError findings with source Parser, category Syntax, and severity Error.
3. Evaluate PSRafScan-owned rules
After parsing, PSRafScan evaluates its own rule files. It does not call, wrap, or depend on PSScriptAnalyzer. Both tools can perform static checking, but they have separate rule contracts and results.
- Pattern rules inspect text at a line or document scope.
- Token rules inspect PowerShell lexical tokens.
- AST rules inspect structured syntax-tree nodes.
- Hybrid rules combine more than one source of evidence.
4. Apply the intended-use context
Choose Ps1File for a source unit meant to remain a saved script. Choose TerminalPaste for code meant to be entered directly in a live terminal. The selection changes rule applicability, not the source's purpose.
RSX -Path ./candidate.ps1 -IntendedUse Ps1File -FailOn Warning5. Read findings and the report
Parser and custom-rule findings share a normalized model: source, rule name, variant, severity, category, line, column, matched text, issue, fix, and raw message. The normalized finding does not include a per-finding File field.
- PlainText is designed for direct human review.
- Json is designed for structured automation and tool handoff.
- OutputPath writes the selected format to a file; otherwise the report is returned to the caller.
6. Interpret FailOn and process results
The FailOn threshold controls the process result. It does not hide lower-severity findings from the report. Current implemented results are 0, 1, and 2.
| Code | Status | Meaning |
|---|---|---|
0 | Pass | No finding met the selected threshold after successful parsing. |
1 | Fail | At least one custom-rule finding met the threshold. |
2 | ParseError | The native parser reported one or more syntax errors. |
7. Make a separate execution decision
A report supports review. It is not a sandbox, malware detector, certification, or proof that a script is safe or correct. Runtime questions still require a deliberately isolated test with known inputs, expected output, minimal privilege, and a recovery plan.