BlastGuard 1.1.1

BlastGuard

Target framework: net10.0 · Type: .NET global tool · Test runner: xUnit

Topics: pull request review · blast radius · code review · risk scoring · GitHub Actions · EF Core migrations · API contracts · security · .NET CLI

BlastGuard gives reviewers a warning label before they start reviewing a pull request.

BlastGuard is a lightweight .NET CLI for scoring pull request risk based on changed files, contracts, configuration, migrations, security-sensitive areas, runtime behaviour, and test signals. It analyses the files changed in a branch or pull request, applies simple deterministic rules, and produces a risk score that helps reviewers understand how far a change could spread if it is wrong.

BlastGuard does not prove a pull request is safe or unsafe. It highlights signals that usually deserve more careful review.

What problem does it solve?

Pull requests can look small while still touching public contracts, database migrations, production configuration, or security-sensitive code. BlastGuard gives reviewers a practical warning label before they start reviewing, so they know where to spend extra attention.

Installation

Install BlastGuard as a .NET global tool:

dotnet tool install --global BlastGuard

See PUBLISHING.md for how releases are published via NuGet trusted publishing.

Basic usage

From a git repository:

blastguard analyse --base origin/main --head HEAD

Compare against a remote base branch:

blastguard analyse --base origin/main --head HEAD

Write JSON output to a file:

blastguard analyse --format json --output blastguard-report.json

Write a Markdown report:

blastguard analyse --format markdown --output blastguard-report.md

Fail a CI step when the score is high:

blastguard analyse --format github --fail-threshold 90

Use a custom configuration file:

blastguard analyse --config blastguard.json

The American spelling analyze is also supported as a command alias.

Example output

BlastGuard report

Score: 76 / 100
Risk: High

Main risk signals:
- Public contract file changed
- EF Core migration changed
- Production appsettings changed
- Authentication code touched
- No test files changed

Suggested review focus:
- Check whether API consumers, message consumers, or generated clients are affected.
- Confirm the migration is backwards compatible.
- Confirm the new configuration exists in every required environment.
- Review authentication, authorisation, claims, and permission behaviour carefully.
- Add or update tests around the highest-risk changed areas.

GitHub Actions usage

Using the BlastGuard action (recommended)

BlastGuard is published on the GitHub Marketplace. The action installs .NET, installs the tool, runs it, and adds the report to the job summary.

To add it from the Marketplace:

1. Open the BlastGuard PR Blast Radius listing.
2. Click Use latest version and copy the snippet, or use the workflow below.
3. Commit the workflow to .github/workflows/blastguard.yml in your repository.

name: BlastGuard

on:
  pull_request:
    branches:
      - main

jobs:
  blastguard:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - uses: kearns2000/BlastGuard@v1
        with:
          base: origin/main
          head: HEAD
          version: 1.1.1

Checkout must use fetch-depth: 0 so origin/main exists for comparison. Pin both the action tag and the version input when you need the action and NuGet tool to stay in lockstep.

Pin to a specific release (for example kearns2000/BlastGuard@v1.1.1) if you prefer reproducible runs over automatic minor updates.

Inputs

Running the tool directly

If you prefer to install and run the tool yourself:

name: BlastGuard

on:
  pull_request:
    branches:
      - main

jobs:
  blastguard:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Install .NET
        uses: actions/setup-dotnet@v5
        with:
          dotnet-version: 10.0.x

      - name: Install BlastGuard
        run: |
          dotnet tool install --global BlastGuard || dotnet tool update --global BlastGuard
          echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"

      - name: Run BlastGuard
        run: blastguard analyse --base origin/main --head HEAD --format github --output blastguard-report.md

      - name: Add report to job summary
        if: always()
        run: |
          if [ -f blastguard-report.md ]; then
            cat blastguard-report.md >> "$GITHUB_STEP_SUMMARY"
          fi

Configuration

BlastGuard reads blastguard.json from the repository root by default. Relative --config paths are resolved against --repo, not the current working directory.

See blastguard.sample.json for a useful starting point.

Supported configuration areas:

• thresholds: customise Low, Medium, High, and Critical score boundaries
• ignorePatterns: glob patterns for generated or irrelevant files
• boundedAreaRoots: path roots used to infer feature or module areas
• securityPathHints: extra path hints for security-sensitive detection
• rules: enable or disable individual rules by id

Example:

{
  "thresholds": {
    "medium": 25,
    "high": 50,
    "critical": 75
  },
  "ignorePatterns": [
    "**/*.Designer.cs",
    "**/*.g.cs"
  ],
  "rules": {
    "database": { "enabled": true },
    "security": { "enabled": true }
  }
}

Scoring model

BlastGuard starts at 0 and adds or subtracts points based on deterministic rules. The final score is clamped between 0 and 100.

Default risk levels:

Rules cover:

• bounded area spread
• public contracts and endpoints
• database and migration changes
• configuration and infrastructure files
• security-sensitive code
• runtime behaviour such as retries, queues, and background workers
• test signals
• dependency changes
• large change size
• documentation-only changes

Negative findings are supported. For example, documentation-only or test-only changes can reduce the score.

Output formats

Supported formats:

• text: human-readable console output
• json: machine-readable output
• markdown: report artefact for local use or upload
• github: compact Markdown suitable for PR comments or job summaries

Design principles

• Deterministic rules over opaque heuristics
• Fast analysis based only on changed files and patch text
• Minimal dependencies
• Clear output aimed at reviewers, not blame
• Easy to extend with new rules later

Known limitations

• BlastGuard does not compile the solution or analyse Roslyn symbols
• Git integration uses the installed git executable
• Route and migration detection uses simple text matching
• Test area matching is intentionally basic in v1
• Binary files are handled gracefully but not deeply analysed

Future ideas

• OpenAPI diffing
• Deeper EF Core migration analysis
• Roslyn-based public API analysis
• GitHub PR comment publishing
• Architecture-specific rules
• SARIF output

Local development

dotnet restore
dotnet build
dotnet test
dotnet pack

Run locally without installing the tool:

dotnet run --project src/BlastGuard.Cli -- analyse --base origin/main --head HEAD

Licence

MIT