Runtime validation can tell you whether configuration is valid when the app starts. ConfigGap checks a different problem earlier: which configuration keys your .NET code statically depends on, and whether your repository actually declares those keys coherently.
ConfigGap is a local .NET tool for ASP.NET Core and other .NET repositories that use IConfiguration or supported Options binding. It never needs configuration values and does not validate production startup state.
dotnet tool install --global KeelMatrix.ConfigGapThe tool targets .NET 8 and exposes the configgap command.
Windows has local performance and targeted test evidence. The repository workflow exercises Release build, full tests, package, and consumer smoke on its configured operating-system matrix. Linux has a reproducible container check; macOS remains unverified locally. See platform support for the matrix, reproducible command, and residual uncertainty.
From a repository containing one solution:
configgap checkSelect a workspace or report format explicitly when needed:
configgap check --solution src/App.sln --format json
configgap check --project src/App/App.csproj --config .configgap.jsonAn explicit --project is analyzed directly. ConfigGap infers a solution only when neither --solution nor --project is supplied; pass both options when selecting one project from an explicit solution.
The JSON report is deterministic and stays on the local output stream.
ConfigGap resolves these access forms when the key is a literal or a supported static expression:
configuration["Payments:Provider"]
configuration.GetValue<string>("Payments:Provider")
configuration.GetSection("Payments")
configuration.GetRequiredSection("Payments")These literal reads remain supported only when the receiver's root provenance is statically established: a root configuration type, a known framework root Configuration property, a local/field/property initialized from a proven root, or a same-compilation helper parameter with at least one visible call site whose arguments are all proven roots. Bounded ASP.NET Core activation recognizes conventional Startup constructors, ControllerBase-derived constructors, and constructors of concrete services explicitly registered through the framework AddScoped, AddSingleton, or AddTransient methods in the same compilation. Outside those explicit framework cases, a parameter with no visible same-compilation call site has no proven root provenance and produces CG900; absence of a caller is never treated as root evidence. A section or otherwise unproven parameter/property/field likewise produces CG900 instead of an invented root key. Local aliases initialized directly from GetSection("Section") retain their section scope.
Supported Options analysis includes statically known section ownership and the framework BindConfiguration("Section") pattern. A writable Options property is not treated as required merely because it exists. ConfigGap keeps known/bindable keys, required keys, and keys actually read by code conceptually separate; v1 reports the statically observed dependency surface.
Declaration surfaces are:
appsettings.jsondiscovered by the default policy;- environment-specific
appsettings.<Environment>.jsonfiles when listed in a version 1 configuration file; .env.example-style name templates when listed in a version 1 configuration file.
The version 1 configuration schema is in docs/configgap-config.schema.json. Paths are relative to the configuration file and must remain inside the repository. JSON values and template values are ignored. Actual .env files are not required or read by default.
Environment names use the same hierarchy mapping as .NET configuration: Payments__Provider and Payments:Provider refer to the same logical key.
Dynamic or unresolvable access is unknown, not broken. It produces CG900 informational output and never creates a blocking missing-key result. Framework-owned keys are excluded from application drift errors.
CG001/ERROR: a statically used application key is absent from the configured declaration surfaces; exit code1.CG002/WARNING: a declared example leaf key was not observed in analyzed code; it never changes a clean exit to1.CG900/INFO: an access could not be resolved statically; it does not change a successful exit to1.CONFIGGAP_*diagnostics: the workspace or configuration could not be analyzed trustworthily; exit code2.
Exit code 0 means a trustworthy analysis completed without blocking findings. 1 means a trustworthy analysis found at least one blocking gap. 2 means no trustworthy result was produced. There are no value-based warnings in the v1 report; declaration values are never needed.
Configuration key names may reveal architecture and can be sensitive. Keep reports local and review them before sharing. After a complete trustworthy analysis, ConfigGap requests the shared activation and heartbeat calls without passing analysis results or configuration data to them. The shared package owns telemetry fields, controls, delivery, and failure handling.
CLI JSON reports also preserve the knownKeys, bindableKeys, requiredKeys, and actuallyReadKeys state arrays. The envelope and all CLI finding codes are defined in docs/configgap-cli-report.schema.json.
Disable telemetry for local or CI validation:
$env:KEELMATRIX_NO_TELEMETRY = "1"See PRIVACY.md for the data boundary and the KeelMatrix.Telemetry privacy policy.
ConfigGap does not inspect secret values, runtime startup state, Kubernetes, Helm, Terraform, Docker Compose, cloud parameter stores, hosted inventories, arbitrary custom providers, remote configuration, deployment manifests, or automatic configuration files. Unsupported and dynamic access remains informational.
Analysis is bounded to 120 seconds, 128 declaration surfaces, and 1 MiB per declaration file. Use --project or an explicit configuration file to narrow a large workspace.
ConfigGap loads projects through MSBuildWorkspace. Restore the selected solution or project with the same .NET SDK used by the repository, then run the command again. If the workspace cannot load, ConfigGap returns exit code 2 and prints an actionable CONFIGGAP_* diagnostic rather than reporting a clean result. See docs/troubleshooting.md.
- Configuration and schema
- Troubleshooting and resource limits
- Analysis resource benchmark
- CLI report schema
- Capabilities and limits
- Security policy
- Changelog
KeelMatrix.ConfigGap is available under the MIT License. See LICENSE.