semanticfw

Semantic Firewall

Detect logic corruption that bypasses code reviews.

Semantic Firewall generates deterministic fingerprints of your Go code's behavior, not its bytes. It uses Scalar Evolution (SCEV) analysis to prove that syntactically different loops are mathematically identical, and a Semantic Zipper to diff architectural changes without the noise.

Quick Start

# Install
go install github.com/BlackVectorOps/semantic_firewall/cmd/sfw@latest

# Fingerprint a file
sfw check ./main.go

# Semantic diff between two versions
sfw diff old_version.go new_version.go

Check Output:

{
  "file": "./main.go",
  "functions": [
    { "function": "main", "fingerprint": "005efb52a8c9d1e3..." }
  ]
}

Diff Output (The Zipper):

{
  "summary": {
    "semantic_match_pct": 92.5,
    "preserved": 12,
    "modified": 1
  },
  "functions": [
    {
      "function": "HandleLogin",
      "status": "modified",
      "added_ops": ["Call <log.Printf>", "Call <net.Dial>"],
      "removed_ops": []
    }
  ]
}

Why Use This?

"Don't unit tests solve this?" No. Unit tests verify correctness (does input A produce output B?). sfw verifies intent and integrity.

• A developer refactors a function but secretly adds a network call → unit tests pass, sfw fails.
• A developer changes a switch to a Strategy Pattern → git diff shows 100 lines changed, sfw diff shows zero logic changes.

Use cases:

• Supply chain security — Detect backdoors like the xz attack that pass code review
• Safe refactoring — Prove your refactor didn't change behavior
• CI/CD gates — Block PRs that alter critical function logic

CI Integration: Blocker & Reporter Modes

sfw supports two distinct CI roles:

1. Blocker Mode: When a PR claims to be a refactor (via title or semantic-safe label), sfw enforces strict semantic equivalence. Any logic change fails the build.

2. Reporter Mode: On feature PRs, sfw runs a semantic diff and generates a drift report (e.g., "Semantic Match: 80%"), helping reviewers focus on the code where behavior actually changed.

GitHub Actions Workflow

name: Semantic Firewall

on:
  pull_request:
    branches: [ "main" ]
    types: [opened, synchronize, reopened, labeled]

jobs:
  semantic-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: Install sfw
        run: go install github.com/BlackVectorOps/semantic_firewall/cmd/sfw@latest

      - name: Determine Mode
        id: mode
        run: |
          if [[ "${{ contains(github.event.pull_request.labels.*.name, 'semantic-safe') }}" == "true" ]] || \
             [[ "${{ contains(github.event.pull_request.title, 'refactor') }}" == "true" ]]; then
            echo "mode=BLOCKER" >> $GITHUB_OUTPUT
          else
            echo "mode=REPORTER" >> $GITHUB_OUTPUT
          fi

      - name: Run Blocker Check
        if: steps.mode.outputs.mode == 'BLOCKER'
        run: sfw check ./

      - name: Run Reporter Diff
        if: steps.mode.outputs.mode == 'REPORTER'
        run: |
          BASE_SHA=${{ github.event.pull_request.base.sha }}
          git diff --name-only "$BASE_SHA" HEAD -- '*.go' | while read file; do
            [ -f "$file" ] || continue
            git show "$BASE_SHA:$file" > old.go 2>/dev/null || touch old.go
            sfw diff old.go "$file" | jq .
            rm old.go
          done

Library Usage

import semanticfw "github.com/BlackVectorOps/semantic_firewall"

src := `package main
func Add(a, b int) int { return a + b }
`

results, err := semanticfw.FingerprintSource("example.go", src, semanticfw.DefaultLiteralPolicy)
if err != nil {
    log.Fatal(err)
}

for _, r := range results {
    fmt.Printf("%s: %s\n", r.FunctionName, r.Fingerprint)
}

Technical Deep Dive

License

MIT License — See LICENSE for details.