leakhunterx-agent 1.1.0rc2

The local scanning runtime for the LeakHunterX security workspace.
Configure scans in the dashboard. Run acquisition and detection on your machine.
Review contextual findings, validation, Delta and reports in one workspace.

Quick start · Architecture · Commands · Documentation · Issues

Python 3.10+   /   Linux · Windows · macOS   /   MIT   /   Source: 1.1.0rc2

One runtime. Multiple sources.

Secret candidates and endpoints retain context and source provenance. The agent journals sanitized evidence before delivery, retries interrupted transfers and keeps completion behind its pending evidence. The backend coordinates workspace access, validation, Delta, exposure review and reporting.

Quick start

1. Install the current source

git clone https://github.com/Omkar443/leakhunterx-agent.git
cd leakhunterx-agent
git switch main
python -m venv .venv

Activate the environment for your operating system:

# Linux / macOS
source .venv/bin/activate

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

python -m pip install .

Install this release candidate with python -m pip install "leakhunterx-agent==1.1.0rc2". Selecting the exact candidate avoids enabling prereleases for unrelated dependencies. Connect using lhx auth, then run lhx agent.

For opt-in background operation on Linux, stop the foreground agent, then use lhx service install and lhx service start. Inspect it with lhx service status and lhx service logs; stop or remove it with lhx service stop / uninstall. Run these as your registered non-root user, without sudo. Installation does not start a service or copy credentials. See Python installation, Linux prerequisites and PyPI publication for setup and release requirements. Check their version: packages and downloaded binaries may precede the source on main. This source is a release candidate; a main-branch push does not publish a stable package or certify final release acceptance.

2. Connect your workspace

In your production workspace, open Agents, generate a connection token, then:

lhx auth

Paste the token at the hidden prompt. Successful registration starts the agent. The default backend is https://backend-leakhunterx.onrender.com.

3. Start a scan

Keep the agent running. In the dashboard, choose New scan, configure an authorized target and select your connected agent. Progress and delivered evidence appear in the workspace. For subsequent starts:

lhx agent

Use lhx status for a read-only connection check; stop the runtime with Ctrl+C. Local sources require explicit target registration. GitHub sources require repository authorization.

Architecture

Control in the workspace. Acquisition and detection on the agent.

flowchart TB
  UI["Security workspace<br/>Targets · Assignments · Live progress"]

  subgraph MACHINE["Local agent / user machine"]
    direction TB
    LOCAL["Local project<br/>Registered filesystem root"]
    GITHUB["GitHub repository<br/>Authorized, pinned commit"]
    WEB["Live website<br/>HTTP + headless browser"]
    ARCHIVE["Historical web<br/>Assigned archive snapshots"]
    ACQUIRE["Scoped acquisition<br/>Consent · Ignore rules · Resource budgets"]
    DETECT["Detection engine<br/>Secret patterns · Endpoints · Context"]
    OUTBOX["Sanitized evidence + durable outbox<br/>Redaction · Stable event IDs · Ordered replay"]
    LOCAL --> ACQUIRE
    GITHUB --> ACQUIRE
    WEB --> ACQUIRE
    ARCHIVE --> ACQUIRE
    ACQUIRE --> DETECT --> OUTBOX
  end

  subgraph CLOUD["Backend / tenant workspace"]
    INGEST["Authenticated ingestion<br/>Tenant access · Evidence persistence"]
    VALIDATE["Contextual validation<br/>AI assessment when available"]
    DELTA["Delta + exposure correlation<br/>Comparable scope · Coverage-aware changes"]
    RESULTS["Dashboard · Exposure review · Reports"]
    INGEST --> VALIDATE --> DELTA --> RESULTS
  end

  UI -->|"Authorized scan assignment"| ACQUIRE
  OUTBOX -->|"Bounded, sanitized evidence"| INGEST

  classDef source fill:#eef3f7,stroke:#657987,color:#15242f
  classDef agent fill:#1c292f,stroke:#78909c,color:#ffffff
  classDef cloud fill:#e9f6ef,stroke:#40846b,color:#143e31
  class LOCAL,GITHUB,WEB,ARCHIVE,UI source
  class ACQUIRE,DETECT,OUTBOX agent
  class INGEST,VALIDATE,DELTA,RESULTS cloud

Detected raw secrets are redacted before delivery. Managed GitHub assignments use temporary, repository-scoped credentials held in agent memory. AI confidence is an assessment of the available evidence, not proof that a credential is active or exploitable. See evidence delivery for the protocol.

Commands

lhx status --json
lhx agent --log-level DEBUG --log-file agent.log
lhx scan ./project --local-only --profile deep --json
lhx ci --commit <default-branch-sha> --policy-id <policy-uuid>

Use lhx <command> --help for the complete syntax. lhx start aliases lhx agent; lhx-agent remains a compatibility entry point. CI reads its credential from LHX_CI_TOKEN, not command-line arguments, and defaults to the production backend.

lhx agent --browser off explicitly limits browser coverage while HTTP crawling continues. Live website scans reject local-only, profile and JSON flags rather than silently ignoring them.

Local targets and offline scans

Create a project in the workspace, then register and explicitly authorize its machine-local target:

lhx project add ./project --name Application --project-id <project-id>
lhx project list
lhx project allow-dashboard <target-id>
lhx agent

For an offline scan without cloud, AI, browser or provider requests:

lhx scan ./project --local-only
lhx scan ./project --local-only --json
lhx resume <scan-id> --json

Use .lhxignore for explicit local exclusions; start from the example. Scan only assets you are authorized to assess. Resource budgets protect the host and target; skipped assets remain visible in coverage.

Documentation

Contributing and verification

python -m pip install -e . pytest
python -m pytest tests -q
python benchmarks/run.py --check --output benchmarks/results/local.json
python benchmarks/run.py --external --check --output benchmarks/results/external-local.json

Real browser integration tests require installed, sandboxed Chromium and LHX_TEST_BROWSER=1. Benchmark scores apply to the labelled synthetic corpus, not arbitrary production sites. The audit records measured results and remaining hosted, soak and package acceptance checks.

python -m pip install . pyinstaller
python packaging/build.py
python packaging/browser_smoke.py dist/<binary-name>

MIT license · Report an issue · Browse releases