Captchaforge

https://lib.rs/crates/captchaforge
Admin
Captchaforge is a Rust library for automatic CAPTCHA detection and solving across multiple...
Tokens:3,681
Snippets:40
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### CaptchaForge CLI Commands

Source: https://lib.rs/crates/captchaforge

Examples of using the CaptchaForge command-line interface for inspecting rules, detecting challenges on a URL, solving challenges, and loading custom rule sets.

```bash
cargo install --path cli
captchaforge inspect-rules                         # list bundled + extra rules
captchaforge detect https://example.com/login      # navigate, run detector
captchaforge solve  https://example.com/login      # navigate, run full chain
captchaforge inspect-rules --rules my-pack.toml    # additive extra rules

```

--------------------------------

### Configure VLM and Third-Party Solvers with TOML

Source: https://lib.rs/crates/captchaforge

Example of a Tier-A operational config file (.captchaforge.toml) for setting solver timeouts, cache TTL, VLM endpoint and model, and third-party service details. Unknown keys will cause a parse error.

```toml
per_solver_timeout_ms = 60000

[cache]
ttl_seconds = 90

[vlm]
endpoint = "http://gpu-host:11434"

[third_party]
service = "cap_solver"
api_key = "..."

```

--------------------------------

### Integrate Solver Telemetry with Custom Collector

Source: https://lib.rs/crates/captchaforge

Example of implementing the SolverTelemetry trait to record solve events, including outcome, time, solver type, and domain. This allows sending event data to a custom collector.

```rust
use std::sync::Arc;
use captchaforge::solver::CaptchaSolverChain;
use captchaforge::telemetry::{SolveEvent, SolverTelemetry};

struct ToProm;
implement SolverTelemetry for ToProm {
    fn record(&self, evt: &SolveEvent<'_>) {
        // ship evt.outcome, evt.time_ms, evt.solver, evt.domain to your collector
    }
}

let chain = CaptchaSolverChain::default_chain()
    .with_telemetry(Arc::new(ToProm));

```

--------------------------------

### Run Architecture Proof Benchmark

Source: https://lib.rs/crates/captchaforge

Execute the architecture proof benchmark to generate a markdown report on latency-critical paths. This command is used for sanity-checking performance regressions.

```bash
```cargo``` run`` --`example` architecture_proof`` --`release``

```

--------------------------------

### Initialize CaptchaSolverChain with VLM Solver

Source: https://lib.rs/crates/captchaforge

Demonstrates using builder methods to programmatically configure a CaptchaSolverChain with a VLM solver, specifying the endpoint and model. This approach offers finer control than environment variables or TOML.

```rust
use captchaforge::solver::{VlmCaptchaSolver, CaptchaSolverChain};

let mut chain = CaptchaSolverChain::empty();
chain.add_solver(
    VlmCaptchaSolver::new()
        .with_endpoint("`http://my-gpu-host:11434`")
        .with_model("`qwen3-vl:30b`"),
);

```

--------------------------------

### Initialize CaptchaSolverChain with Third-Party Solver

Source: https://lib.rs/crates/captchaforge

Shows how to add a third-party solver to the CaptchaSolverChain, configuring it for a specific service like CapSolver and providing an API key. The solver is skipped if no API key is configured.

```rust
use captchaforge::solver::{ThirdPartyCaptchaSolver, CaptchaSolverChain};

let mut chain = CaptchaSolverChain::empty();
chain.add_solver(
    // Pick the service flavour, then pass the key:
    ThirdPartyCaptchaSolver::cap_solver().with_api_key("`...`"),
);

```

--------------------------------

### Apply Captured Cookies to Page

Source: https://lib.rs/crates/captchaforge

Apply captured session cookies to a page for subsequent navigations to preserve the WAF/vendor's trusted session.

```rust
captchaforge::cookies::apply_to_page(&mut page, &result.cookies)
```

--------------------------------

### Add captchaforge to Cargo.toml

Source: https://lib.rs/crates/captchaforge

Add captchaforge and chromiumoxide as dependencies in your Cargo.toml file. Pin the version for stability as the public API may change before 1.0.

```toml
[dependencies]
captchaforge = { git = "https://github.com/santhsecurity/captchaforge", branch = "main" }
chromiumoxide = "0.9"
tokio = { version = "1", features = ["full"] }

```

--------------------------------

### Control CAPTCHA solving with CaptchaSolverChain

Source: https://lib.rs/crates/captchaforge

For full control, use `CaptchaSolverChain` to manage telemetry, token caching, and custom solvers. This allows for fine-grained configuration and integration with caching mechanisms.

```rust
use std::sync::Arc;
use captchaforge::{
    detect,
    solver::{
        CaptchaSolverChain,
        TokenCache,
    },
};

let cache = Arc::new(TokenCache::new()); // 60s TTL by default
let chain = CaptchaSolverChain::default_chain()
    .with_token_cache(cache); // hit cache before solving

let info = detect::detect(page).await?;
if detect::is_captcha(&info) {
    let outcome = chain.solve(page, &info).await;
    // ...
}

```

--------------------------------

### Register Built-in Rules

Source: https://lib.rs/crates/captchaforge

Register the bundled community rule pack for extended captcha detection capabilities.

```rust
ProviderRegistry::with_built_in_rules()
```

--------------------------------

### Auto-solve CAPTCHA with captchaforge

Source: https://lib.rs/crates/captchaforge

Use the `auto_solve` function for a convenient one-call solution to detect and solve CAPTCHAs. It returns `Ok(None)` if no CAPTCHA is found on the page.

```rust
async fn handle_captcha(page: &chromiumoxide::Page) -> anyhow::Result<()> {
    // One-call convenience: detect, then run the default solver chain
    // if a captcha is present. Returns Ok(None) for no-captcha pages.
    if let Some(outcome) = captchaforge::auto_solve(page).await? {
        if outcome.success {
            tracing::info!(method = ?outcome.method, "captcha solved");
        } else if let Some(screenshot) = outcome.screenshot {
            tracing::warn!(bytes = screenshot.len(), "human review needed; screenshot attached");
        }
    }
    Ok(())
}

```

--------------------------------

### CaptchaSolverChain

Source: https://lib.rs/crates/captchaforge

Provides fine-grained control over the CAPTCHA solving process, allowing for custom solvers, token caching, and telemetry.

```APIDOC
## CaptchaSolverChain

### Description
Allows for advanced CAPTCHA solving configurations, including using a token cache, custom solver chains, and telemetry.

### Method
`CaptchaSolverChain::default_chain()` - Creates a default solver chain.
`chain.with_token_cache(cache)` - Adds a token cache to the chain.
`chain.solve(page, info)` - Solves the CAPTCHA using the configured chain.

### Parameters
* `page` (*&chromiumoxide::Page*) - A reference to the headless browser page.
* `info` (*&CaptchaInfo*) - Information about the detected CAPTCHA.
* `cache` (*Arc<TokenCache>*) - An optional shared token cache.

### Request Example
```rust
use std::sync::Arc;
use captchaforge::{
    detect,
    solver::{
        CaptchaSolverChain,
        TokenCache
    }
};

let cache = Arc::new(TokenCache::new());
let chain = CaptchaSolverChain::default_chain()
    .with_token_cache(cache);

let info = detect::detect(page).await?;
if detect::is_captcha(&info) {
    let outcome = chain.solve(page, &info).await;
    // ... handle outcome
}
```
```

--------------------------------

### detect

Source: https://lib.rs/crates/captchaforge

Functions for detecting CAPTCHAs on a page, including a high-level `is_captcha` check and a detailed detection function.

```APIDOC
## detect

### Description
Provides utilities for detecting CAPTCHAs on a web page.

### Methods
* `detect::detect(page: &chromiumoxide::Page) -> impl Future<Output = anyhow::Result<CaptchaInfo>>` - Performs a detailed detection of CAPTCHAs on the page.
* `detect::is_captcha(info: &CaptchaInfo) -> bool` - Checks if the provided `CaptchaInfo` indicates the presence of a CAPTCHA.

### Parameters
* `page` (*&chromiumoxide::Page*) - A reference to the headless browser page.
* `info` (*&CaptchaInfo*) - Information about the detected CAPTCHA.

### Response
* `CaptchaInfo` - An object containing details about any detected CAPTCHAs.
* `bool` - `true` if a CAPTCHA is detected, `false` otherwise.

### Request Example
```rust
let info = detect::detect(page).await?;
if detect::is_captcha(&info) {
    // CAPTCHA detected, proceed with solving
}
```
```

--------------------------------

### Add Custom Solver to Chain

Source: https://lib.rs/crates/captchaforge

Add a custom solver by implementing the CaptchaSolver trait and adding it to the chain before default strategies.

```rust
chain.add_solver(MySolverImplementation)
```

--------------------------------

### auto_solve

Source: https://lib.rs/crates/captchaforge

A one-call convenience function to automatically detect and solve CAPTCHAs present on a page. It returns `Ok(None)` if no CAPTCHA is detected.

```APIDOC
## auto_solve

### Description
Automatically detects and solves CAPTCHAs on the current page using the default solver chain. Returns `Ok(None)` if no CAPTCHA is found.

### Method
`async fn auto_solve(page: &chromiumoxide::Page) -> anyhow::Result<Option<SolveOutcome>>`

### Parameters
* `page` (*&chromiumoxide::Page*) - A reference to the current headless browser page.

### Response
* `SolveOutcome` - An object containing the result of the solve attempt, including success status, method used, and an optional screenshot.

### Request Example
```rust
if let Some(outcome) = captchaforge::auto_solve(page).await? {
    if outcome.success {
        tracing::info!("captcha solved");
    } else if let Some(screenshot) = outcome.screenshot {
        tracing::warn!("human review needed; screenshot attached");
    }
}
```
```
Tokens:
Raw