Embedding Picket

Picket exposes five AOT-safe library packages for host applications:

• Picket.Compat: Gitleaks-compatible configuration, built-in rule sets, baselines, and ignore files.
• Picket.Engine: byte-oriented scanning over caller-owned buffers.
• Picket.Report: Gitleaks-compatible and Picket-native report writers.
• Picket.Rules: rule and allowlist models.
• Picket.Security: egress and endpoint safety primitives for live verification and source connectors.

These packages target net9.0 and net10.0, enable trim, Native AOT, and single-file analyzers, and avoid dynamic plugin or reflection-only runtime behavior. The current library surface is intentionally narrow. Picket.Sources, Picket.Store, Picket.Verify, Picket.Analyze, and TUI internals are implementation or workflow assemblies and are not public library packages yet.

Picket also publishes RID-specific Native AOT dotnet tool packages for package-manager workflows:

dotnet tool install --global Picket
dotnet tool install --global Picket.Tui.Cli

The top-level tool packages are pointer packages; the matching RID packages contain the native executables selected by the .NET CLI during install. Picket publishes Windows, Linux, and macOS x64/Arm64 tool packages.

Install

<ItemGroup>
  <PackageReference Include="Picket.Compat" Version="0.1.13" />
  <PackageReference Include="Picket.Engine" Version="0.1.13" />
  <PackageReference Include="Picket.Report" Version="0.1.13" />
  <PackageReference Include="Picket.Rules" Version="0.1.13" />
  <PackageReference Include="Picket.Security" Version="0.1.13" />
</ItemGroup>

Picket.Engine depends on Picket.Rules. Picket.Compat and Picket.Report depend on both. Picket.Security has no Picket package dependencies. Hosts can reference only the highest-level package they need.

Load Built-In Rules

Use PicketConfigLoader for the native default rule set and GitleaksConfigLoader when strict Gitleaks compatibility is required:

using Picket.Compat;
using Picket.Rules;

RuleSet nativeRules = PicketConfigLoader.LoadDefaultRuleSet();
RuleSet compatibleRules = GitleaksConfigLoader.LoadDefaultRuleSet();
RuleSet strictRules = PicketConfigLoader.LoadBuiltInRulePack(PicketRulePackNames.Strict);

The built-in loading methods do not read environment variables or target-local files. Stable identifiers are available from PicketRulePackNames for gitleaks, picket-default, picket-strict, and picket-experimental.

Use LoadRuleSet(configPath, source) when the host intentionally wants native CLI configuration precedence. Pass opt-in packs after the source to layer them over the resolved configuration:

RuleSet resolvedRules = PicketConfigLoader.LoadRuleSet(
    configPath,
    source,
    PicketRulePackNames.Strict,
    PicketRulePackNames.Experimental);

Scan a Buffer

using System.Text;
using Picket.Engine;
using Picket.Report;
using Picket.Rules;

RuleSet rules = new([
    new SecretRule(
        "sample-token",
        "Sample token",
        "token-[0-9]+",
        keywords: ["token"],
        tags: ["example"])
]);

ScanRequest request = new(
    Encoding.UTF8.GetBytes("token-12345"),
    "sample.txt",
    rules);

IReadOnlyList<Finding> findings = SecretScanner.Scan(request);
string jsonl = PicketJsonlReportWriter.Write(findings);

Callers own the input buffer. ScanRequest accepts ReadOnlyMemory<byte> so hosts can scan bytes from files, archives, git objects, IDE buffers, or generated content without forcing a string conversion before matching.

Pass cancellationToken when scan work is tied to an editor request, web request, background job, or CI timeout. The scanner polls cancellation while evaluating rules and deterministic native matchers so long-running inputs can stop without waiting for the next file boundary.

Rule Compilation

ScanRequest can accept a RuleSet and compile it for one scan. Hosts that scan many inputs should compile once and reuse the compiled rule set:

CompiledRuleSet compiledRules = CompiledRuleSet.Compile(rules);

ScanRequest request = new(
    input,
    path,
    compiledRules,
    maxDecodeDepth: 5,
    maxTargetBytes: 50_000_000);

The compiled rule set owns Scout byte regexes and keyword prefilters. It is safe to reuse across scans when the rule configuration does not change.

Reporting

Use the Gitleaks writers when an existing integration expects Gitleaks-compatible fields and ordering. Use Picket writers for native metadata such as validation state, secret and match hashes, provenance, confidence, severity, and JSONL streaming.

Recommended defaults for embedders:

• Keep secrets redacted before logging or diagnostics.
• Use JSONL for large result streams and CI/event ingestion.
• Use SARIF for GitHub code scanning and editor/security tooling.
• Keep Gitleaks-compatible reports separate from Picket-native reports.

Endpoint Safety

Use EndpointGuardHttpHandlerFactory when live verification or source-provider code contacts an endpoint that may be configured by users, rules, or environment. The handler disables automatic redirects and re-applies EndpointGuard to the IP address resolved for the actual socket connection:

using System.Net.Http;
using Picket.Security;

var guardOptions = new EndpointGuardOptions
{
    RequireHttps = true,
};

using var httpClient = new HttpClient(EndpointGuardHttpHandlerFactory.Create(new EndpointGuardHttpHandlerOptions
{
    EndpointGuardOptions = guardOptions,
}), disposeHandler: true);

Use EndpointGuard.Evaluate for preflight diagnostics or when a host API needs to decide before constructing an HTTP client:

using System.Net;
using Picket.Security;

EndpointGuardResult decision = EndpointGuard.Evaluate(
    new Uri("https://api.github.com/user"),
    [IPAddress.Parse("140.82.112.6")]);

if (!decision.IsAllowed)
{
    throw new InvalidOperationException(decision.Message);
}

The default guard requires HTTPS and blocks loopback, private, link-local, metadata-service, reserved, multicast, documentation, IPv4-mapped, IPv4-compatible, NAT64, 6to4, Teredo-to-non-public, and site-local addresses. Tests and local fakes can opt in to non-public endpoints with EndpointGuardOptions.AllowNonPublicAddresses.

Native AOT Hosts

The public packages are designed for Native AOT hosts:

• No runtime code generation is required.
• No dynamic assembly loading is required.
• Public APIs use concrete documented shapes.

Hosts should keep trim and AOT analyzer warnings enabled. If a host publishes Native AOT, unresolved warnings from Picket packages should be treated as bugs.