GlobalGuard.Analyzers 1.0.0-preview.1

GlobalGuard.Analyzers

Compile-time privacy and performance enforcement for .NET — built for the African cloud market and reusable everywhere.

GlobalGuard is a Roslyn analyzer that catches two classes of bugs before they reach production: PII fields leaking into logs, and synchronous thread-blocking that inflates cloud costs. Both checks run inside the compiler: no runtime overhead, no separate scan step, no CI plugin to install.

Why GlobalGuard?

The compliance problem

Data-protection laws now cover every market where African companies operate:

The single most common violation across all three: a developer writes _logger.LogInformation(user.Bvn) during a debugging session and the line ships to production. By the time a compliance audit catches it, the data is in log aggregators, backups, and third-party SIEM tools.

GlobalGuard makes that mistake a compiler error.

The cost problem

task.Result, task.Wait(), and task.GetAwaiter().GetResult() are the three most common causes of deadlocks and thread-pool starvation in .NET web applications. In cloud-hosted services (Azure App Service, AWS Elastic Beanstalk, any Kubernetes workload) each blocked thread is a unit of capacity that you're paying for but not using.

GlobalGuard flags every occurrence as a compiler warning and offers a one-click fix that rewrites the method signature to async/await.

Quick start

Install

<PackageReference Include="GlobalGuard.Analyzers" Version="1.0.0-preview.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

Or via the CLI:

dotnet add package GlobalGuard.Analyzers --version 1.0.0-preview.1

See it in action

Add a .globalguard.json to your project root (the package's MSBuild props auto-discovers it — no <AdditionalFiles> entry needed):

{
  "activeRegions": ["Nigeria", "Global"],
  "additionalPiiNames": ["staff_id", "salary"]
}

Then write any of the following and your build will immediately fail or warn:

// GG_SEC_001 — error: BVN flowing into a log
_logger.LogInformation("Processing {bvn}", bvn);

// GG_SEC_001 — error: NIN inside an interpolated string
_logger.LogError($"Retry for NIN {nin}");

// GG_PERF_001 — warning: thread-blocking a Task
var result = FetchUserAsync().Result;
var data   = GetDataAsync().GetAwaiter().GetResult();

Diagnostics

GG_SEC_001 — PII Sentinel

What it detects

• Direct variable references in calls to any method containing "Log" or "Print" in the name
• PII inside interpolated strings: $"id: {national_id}" is caught just as reliably as Log(national_id)
• Fields and properties decorated with [PersonalData] or [PiiData] attributes, regardless of name
• Name-heuristic fallback for common identifiers across five regional packs (see Region packs)

What it does not flag (no false positives)

• Log(GlobalGuard.Redact(bvn)) — already wrapped; stops the walk
• Log(Sanitize(bvn)) — user-written sanitising call; outer invocation stops the walk
• SaveToDatabase(bvn) — not a logging call

Two fix actions per diagnostic

1. Wrap with GlobalGuard.Redact() — inserts GlobalGuard.Redact(bvn) at the call site. You own the Redact implementation: hash, mask, tokenise — your choice.
2. Suppress with [SuppressMessage] — adds [System.Diagnostics.CodeAnalysis.SuppressMessage("Security", "GG_SEC_001:...", Justification = "Reviewed")] to the containing method. For the rare cases where logging the field is intentional and reviewed.

GG_PERF_001 — Naira Saver

What it detects

What the fix does

Given:

string GetUser() {
    return _client.FetchAsync().Result;
}

One click produces:

async Task<string> GetUser() {
    return await _client.FetchAsync();
}

The fix handles all four return-type cases:

• void → Task
• T → Task<T>
• Task → Task (no change)
• Task<T> → Task<T> (no change)

It also adds using System.Threading.Tasks; when the namespace is not already present.

GG_PERF_002 — Queryable ForEach (reserved, coming in v1.1)

Detects IQueryable<T>.ForEach(...) patterns that cause full table scans instead of server-side filtering. Implementation deferred to v1.1.

Region packs

PII name detection uses an attribute-first check ([PersonalData], [PiiData]) with a name-heuristic fallback. The heuristic draws from regional name packs. Nigeria is always active; others are opt-in via .globalguard.json.

Name matching is case-insensitive: BVN, Bvn, and bvn all trigger the diagnostic.

Adding your own names

{
  "activeRegions": ["Nigeria", "EU", "Global"],
  "additionalPiiNames": ["staff_id", "employee_number", "salary", "grade_level"]
}

Configuration reference

.globalguard.json

Place this file at your project root. The NuGet package's bundled MSBuild .props file automatically registers it as an AdditionalFiles input — no <AdditionalFiles> entry required in your .csproj.

{
  "activeRegions": ["Nigeria", "Global"],
  "additionalPiiNames": []
}

If the file is absent or malformed, GlobalGuard falls back to the default registry (Nigeria + Global packs), so your build never breaks due to a misconfigured config file.

.editorconfig severity overrides

[*.cs]
dotnet_diagnostic.GG_SEC_001.severity = error    # default
dotnet_diagnostic.GG_PERF_001.severity = warning # default
dotnet_diagnostic.GG_PERF_002.severity = none    # default (reserved)

Promote GG_PERF_001 to an error to block any PR that introduces a new blocking call:

dotnet_diagnostic.GG_PERF_001.severity = error

Silence a specific file or folder:

[**/Migrations/**.cs]
dotnet_diagnostic.GG_SEC_001.severity = none

CI / GitHub Actions

The package ships with a production-ready workflow at .github/workflows/globalguard-ci.yml.

Key properties of the design:

• GG_SEC_001 is DiagnosticSeverity.Error. dotnet build exits non-zero if any PII leak is detected. The PR is blocked without any /warnaserror flag or additional configuration.
• SARIF output is emitted via /p:ErrorLog=results/globalguard.sarif,version=2 so violations appear as line-level annotations directly on the pull request diff in GitHub.
• upload-sarif runs if: always() — annotations appear even when the build step fails, so the developer sees exactly which line to fix.
• A separate pack job runs only on main, producing a versioned .nupkg artifact automatically.

What a blocked PR looks like

❌  Build (emit SARIF)
    src/UserService.cs(42,38): error GG_SEC_001:
    Argument 'bvn' may contain PII.
    Wrap with GlobalGuard.Redact() or suppress with [SuppressMessage].

The GitHub Security tab also shows all violations grouped by rule, file, and commit, giving your security team a full audit trail.

Architecture

GlobalGuard.Analyzers.dll  (in-process: IDE, MSBuild, CI)
  ┌─ Infrastructure
  │    PiiNameRegistry ← AnalyzerConfigReader ← .globalguard.json (AdditionalFiles)
  │    ITelemetrySink (no-op stub, extensible)
  │    IAiFixer       (no-op stub — no HTTP calls in-process)
  ├─ Security
  │    GG_SEC_001  PiiSentinelAnalyzer + PiiSentinelCodeFixProvider
  └─ Performance
       GG_PERF_001  NairaSaverAnalyzer + NairaSaverCodeFixProvider
       GG_PERF_002  QueryableForEachAnalyzer (stub, reserved)

── Roslyn compiler boundary ──────────────────────────────────────────────────
  .editorconfig        → severity overrides   (automatic)
  #pragma warning      → inline suppression   (automatic)
  /p:ErrorLog=...      → SARIF emission        (automatic)

FUTURE — dotnet-globalguard CLI  (out-of-process)
  Implements IAiFixer via LLM API
  References GlobalGuard.Analyzers as a plain library
  Never loaded in-process by Roslyn

Why no HTTP calls in the analyzer? Roslyn analyzers run inside the IDE process (Visual Studio, Rider, VS Code via OmniSharp). An HTTP call from inside that process causes the IDE to hang while the request is in flight, blocks the Roslyn worker thread, and exposes API keys via dotnet userSecrets or environment variables that IDE host processes can read. The AI suggestion path is architecturally isolated behind IAiFixer for a future out-of-process CLI.

Test coverage

54 tests across six test classes, all green:

Package structure

GlobalGuard.Analyzers.1.0.0-preview.1.nupkg
├── analyzers/
│   └── dotnet/
│       └── cs/
│           └── GlobalGuard.Analyzers.dll    ← loaded by Roslyn, not added to references
├── build/
│   ├── GlobalGuard.Analyzers.props          ← auto-discovers .globalguard.json
│   └── GlobalGuard.Analyzers.targets
└── GlobalGuard.Analyzers.nuspec

IncludeBuildOutput=false ensures there is no lib/ folder. The DLL is never added as a compile-time reference to consumer projects, preventing type-duplicate errors when multiple projects in a solution install the package.

SuppressDependenciesWhenPacking=true means the .nuspec has an empty <dependencies> section. Roslyn, Workspaces, and System.Text.Json are all PrivateAssets=all — they do not appear in the consumer's dependency graph.

Roadmap

Contributing

1. Fork and clone the repository
2. dotnet restore && dotnet build — should compile with zero errors
3. dotnet test — all 54 tests must pass before submitting a PR
4. Add a new region pack? Add names to PiiNameRegistry.cs and test cases to PiiNameRegistryTests.cs
5. New diagnostic rule? Follow the NairaSaverAnalyzer + NairaSaverCodeFixProvider pair as a template

License

MIT © 2026 GlobalGuard Contributors