Crate adler_core 

Core engine for the Adler OSINT username-search tool — runtime-agnostic, embed-friendly.

The CLI lives in adler-cli; this crate is what you reach for to drive username detection from your own Rust code (a Discord bot that checks usernames, a security tool that flags exposed identities across a watchlist, a CI gate that asserts a name isn’t claimed elsewhere, …).

Quick start

Scan the embedded 1,900-entry main registry for one username and print the hits:

use adler_core::{Client, ExecutorOptions, MatchKind, Registry, Username, executor};

let registry = Registry::default_embedded()?;

// filter(include, exclude, tags, exclude_tags, include_nsfw)
// — empty slices = no name/tag filter; `false` keeps the
// default NSFW auto-exclusion (matches Sherlock's `--nsfw`
// opt-in). Pass `true` (or `&["nsfw".into()]` as tags) to
// scan adult-content sites.
let sites = registry.filter(&[], &[], &[], &[], false);

let username = Username::new("torvalds")?;
let client = Client::builder().build()?;

let outcomes =
    executor::run(&client, &sites, &username, ExecutorOptions::default()).await;

for outcome in outcomes.iter().filter(|o| o.kind == MatchKind::Found) {
    println!("{} → {}", outcome.site, outcome.url);
}

Map of the public API

Detection plumbing:

• Registry — loaded, validated collection of sites. Build from the embedded default_embedded, from a JSON string (from_json_str), or from disk (load_from_path).
• Site, Signal, UrlTemplate, Extractor, KnownPresent — site-registry value types. Site is serde-(de)serialisable; the JSON Schema lives in docs/sites.schema.json.
• Username — validated search target. Constructed via Username::new; invalid characters / overlong names are rejected at construction time.
• Client, ClientBuilder — reqwest-backed probe issuer. Knobs the builder exposes: timeout, redirect limit, per-host / global throttle, retry policy, user-agent rotation pool, proxy, robots.txt cache, browser backend, browser budget.
• CheckOutcome, MatchKind, UncertainReason — verdict types. The signal pipeline is negative-priority: any NotFound vote wins over Found; no votes → Uncertain. A per-site regex_check mismatch short-circuits with UncertainReason::UsernameNotAllowed before any HTTP request.
• executor — bounded-concurrency fan-out runner. Pass an ExecutorOptions to control concurrency, deadline, and progress callback.

Optional analysis:

• correlate — group accounts that look like the same person across sites via enriched profile fields.
• permute — generate username variants (alice → alice1, alice.dev, …) via MAX_VARIANTS / PermuteLevel.
• WatchlistConfig — serde-compatible watchlist configuration for usernames, aliases, and optional site/tag scopes.
• doctor — registry health check (check_site), signature derivation (suggest_fix), known-present discovery (discover_known_present), site scaffolding (scaffold_site).

Bot-protected sites (Instagram, X/Twitter today):

• BrowserBackend trait — abstract real-Chrome driver. Configurable on the Client via ClientBuilder::browser. Built-in implementations: browser::local::LocalBackend (free, via chromiumoxide) and browser::browserbase::BrowserbaseBackend (cloud, residential IPs, in-tree raw async CDP client). BrowserBudget caps browser-routed fetches per scan to keep cost predictable.

Cache

Cache persists per-(site, username, signal-signature) verdicts between runs. Compose with Client via the builder or skip entirely for one-shot scans.

Error model

Result is a Result<T, Error> alias; Error is a single crate-level thiserror enum. The probe path never surfaces errors — transient network failures become MatchKind::Uncertain with a typed UncertainReason, so you get a partial result for every site even when the network is flaky. Loader errors (malformed registry JSON, invalid CSS selectors, regex compile failures) come back as Err.

Version history

Pre-1.0 SemVer. Breaking changes since 0.1:

• 0.2.0 — added Site::request_headers (BTreeMap<String, String>); BrowserBackend::fetch gained the headers parameter; browser module became pub.
• 0.3.0 — Site::known_present changed from Option<String> to Option<KnownPresent> (the new enum accepts string-or-array via untagged serde); DoctorReport::Healthy::present and Unhealthy::present changed from Option<CheckOutcome> to Vec<(String, CheckOutcome)> (one entry per probed candidate).
• 0.4.0 — Registry::filter gained a fifth include_nsfw: bool parameter (default-exclude adult sites); UncertainReason gained UsernameNotAllowed; Site::regex_check field added (per-site username regex).

Each change has a migration block in the CHANGELOG.

Re-exports

pub use browser::BrowserBackend;

pub use browser::BrowserBudget;

pub use browser::RenderedPage;

pub use doctor::DoctorReport;

pub use doctor::ExtractSuggestion;

pub use doctor::FixSuggestion;

pub use executor::ExecutorOptions;

Modules

browser

Browser backend for pages that are unusable from raw HTTP.

doctor

Site signature health check.

executor

Concurrent fan-out runner for site probes.

telemetry

Cross-scan telemetry analysis — close the doctor loop on sites that consistently need the browser backend.

Structs

AccessPolicy

What a site needs from its egress. The default (empty) means “no special routing” — the request uses the client’s default egress.

Cache

In-memory cache backed by a JSON file.

CheckOutcome

Result of probing a single site for a username.

Client

HTTP client used to probe sites.

ClientBuilder

Builder for Client.

Cluster

A group of accounts that likely belong to the same person.

ConfidenceScore

Confidence attached to a single scan outcome.

CorrelationReport

Result of correlating a scan’s outcomes.

CountryCode

ISO-3166-1 alpha-2 country code, stored lowercased (e.g. pl, de). A newtype so a geo requirement can’t be confused with an arbitrary string and is validated at the boundary.

EgressSpec

A configured egress (proxy) the client can route through.

EgressSummary

Read-only metadata for one configured egress, surfaced via Client::egress_summary.

Engine

Shared detection signature template for a family of sites that run the same forum / blog / wiki software (Discourse, vBulletin, XenForo, MediaWiki, …). Referenced from Site::engine.

EscalationBudget

Per-scan ceiling on automatic escalation attempts.

EvidenceAccessPath

Non-secret access context for an evidence item.

EvidenceSource

Source metadata attached to every normalized evidence item.

Extractor

A rule for extracting one profile field from a page.

HistoricalScanRef

Borrowed scan metadata needed to compare one scan against prior scans.

IdentityCluster

A deterministic candidate group of profiles that likely belong together.

InvestigationReport

Structured report over one scan or scan-derived artifact.

InvestigationReportBuilder

Builder for optional report inputs that do not live in CheckOutcome.

ObservedProfile

A positive profile observation suitable for identity-level reasoning.

ProfileEvidence

A normalized fact observed on a profile or profile-like endpoint.

RawResponse

Raw response data returned by Client::fetch for diagnostics.

Registry

A loaded, validated collection of site definitions.

ReportAccount

Found account row used by report sections.

ReportDisabledSite

Disabled or parked site omitted from the scan scope.

ReportEvidence

One structured evidence table row.

ReportLimitation

Explicit caveat for the report.

ReportSummary

Aggregate counts used by report renderers.

ReportTimelineEvent

Optional history event supplied by timeline/watchlist layers.

ReportUncertainAccount

Inconclusive account row.

ScanSchedule

Repeated scan policy for a watchlist.

Session

An operator-supplied authenticated session for a site: a bag of HTTP headers (typically Cookie, sometimes Authorization / CSRF tokens) applied to probes for sites whose access.session names it.

SessionStore

Named-session store, indexed by the name a site references via access.session. Empty by default → a no-op.

Site

One site we can probe for the existence of an account.

SiteFilter

Reusable site-filter specification shared by CLI, server, and MCP surfaces.

UrlTemplate

URL template containing a {username} placeholder.

Username

A validated username.

WatchScanTarget

Concrete scan work item derived from a watchlist.

WatchScope

Site/tag scope for watchlist scans.

WatchTarget

One watched identity.

WatchlistConfig

Top-level watchlist configuration.

Enums

ClusterReason

Deterministic reasons used to link observed profiles.

ConfidenceLabel

Human-facing confidence bucket.

ConfidenceReason

Machine-readable confidence rationale.

EgressKind

The kind of network an egress exits from.

Error

Errors produced by the Adler engine.

EvidenceOrigin

Adler subsystem that produced an evidence item.

HttpMethod

HTTP method used to probe a site. Only GET and POST are supported.

KnownPresent

Known-present declaration on a Site.

MatchKind

Outcome of a single site probe.

PermuteLevel

How aggressively to expand a username into variants.

ProfileEvidenceKind

Profile evidence categories that higher-level analysis can reason over.

ProtectionKind

A specific anti-bot mechanism a site is known to deploy. Used to route probes to the right backend (raw HTTP, cloudscraper, full browser) and to inform users what blocks reliable detection.

ReportLimitationKind

Limitation categories.

ReportTimelineEventKind

Timeline event categories available to report renderers.

Signal

A single piece of evidence about whether an account exists.

TransportTier

Which transport actually produced an outcome.

UncertainReason

Why a probe was inconclusive.

WatchlistError

Watchlist validation error.

Constants

BOT_PROTECTED_TAG

Registry tag marking a site as bot-protected.

DEFAULT_BROWSER_BUDGET

Default ceiling on browser-backed probes per scan when no other value is specified.

DEFAULT_ESCALATION_BUDGET

Default ceiling on automatic escalation fetches per scan (HTTP / impersonate → browser when the cheap path returns Uncertain(CloudflareChallenge | RateLimited)).

INVESTIGATION_REPORT_SCHEMA_VERSION

Current schema version for investigation report JSON.

LINK_THRESHOLD

Minimum pairwise score to link two accounts.

MAX_VARIANTS

Hard cap on the number of variants returned (including the original).

WATCHLIST_CONFIG_SCHEMA_VERSION

Current schema version for watchlist configuration documents.

Functions

build_identity_clusters

Build deterministic identity clusters from scan outcomes.

correlate

Correlate Found accounts by their enrichment fields.

historical_consistency_counts

Count previous stable Found observations per current Found site.

permute

Expand username into a deduplicated list of variants per level.

render_investigation_report_html

Render a self-contained, no-JS HTML investigation report.

render_investigation_report_markdown

Render a deterministic Markdown investigation report.

Type Aliases

Result

Result alias used throughout the engine.