feat: add hybrid analysis datasource

[jaspermayone]

Closes #56.

Adds Phish::HybridAnalysisService, a datasource for the Hybrid Analysis (Falcon Sandbox) public API v2.

What it does

The service posts to search/terms and asks which sandbox reports mention a domain or a URL. It reads only. Submitting a URL for a new scan needs an elevated key, and a restricted key (the level a free account starts at) gets a 403, so the service never submits.

flowchart TD
    A[check_domain / check_url] --> B{cached?}
    B -- yes --> C[cached result]
    B -- no --> D[reserve rate limit slot]
    D --> E[POST search/terms]
    E --> F{any reports?}
    F -- no --> G[unknown 0.0]
    F -- yes --> H[tally report verdicts]
    H --> I{any malicious?}
    I -- no --> J[suspicious / clean / unknown]
    I -- yes --> K{domain and minority malicious?}
    K -- yes --> L[suspicious]
    K -- no --> M[phishing]

Loading

Scoring

A search hit is not a conviction, and the two search terms do not carry the same weight:

• A url search matches reports for that exact URL, so a malicious report is about the thing we asked about. Confidence tops out at 0.9.
• A domain search matches every report whose sample contacted the domain. Shared hosting, URL shorteners and CDNs collect malicious reports without being phishing themselves. Confidence tops out at 0.7, and a domain needs at least half of its reports to say malicious before the verdict is phishing instead of suspicious.

Confidence blends how much of the evidence agrees with the worst threat_score in the page of reports, and never falls below 0.35, which keeps a real hit above the aggregator's 0.3 floor.

Rate limits and caching

A restricted key allows 5 requests per minute and 200 per hour. That is too tight for the per request path, so the service stays out of AggregatorService::DEFAULT_SERVICES and caches results for 12 hours, the same shape as Pulsedive. It is registered in ServiceFactory, so PhishServiceRetryJob and on demand callers can use it.

Other changes

• BaseService#connection takes a request_encoding option. Hybrid Analysis answers a JSON body with a 400, so this service asks for :url_encoded. Every existing caller keeps the :json default.
• New credential: hybrid_analysis.api_key. Documented in README.md and CLAUDE.md. The service raises AuthenticationError when it is absent.

Testing

21 new tests cover the verdict mapping, the domain and URL ceilings, the report cap, normalization, form encoding, the api-key header, caching, the local rate limit, 403 and 429.

• bin/rails test: 388 runs, 0 failures
• bin/rubocop: no offenses
• bin/brakeman: no warnings

https://claude.ai/code/session_01DMcyASE3TtpFxNmDKzNxjY

[coderabbitai]

Warning

Review limit reached

Next included review available in 28 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: 3acc326c-8fb7-4895-9afd-8e7ea4762afd

📥 Commits

Reviewing files that changed from the base of the PR and between 6eee697 and 2bbfc0b.

📒 Files selected for processing (6)

• CLAUDE.md
• README.md
• app/services/phish/base_service.rb
• app/services/phish/hybrid_analysis_service.rb
• app/services/phish/service_factory.rb
• test/services/phish/hybrid_analysis_service_test.rb

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}