theharvester-service

A Laravel package that runs theHarvester OSINT scans as ephemeral Docker containers and stores the parsed results. Given a target domain, it spins up one or more secsi/theharvester containers through the Docker Engine API, runs the scan, collects the logs, and extracts the number of IPs, emails, and hosts discovered.

Built on the Spatie package skeleton, with GitHub Actions CI, Pint, Larastan, and Pest.

Requirements

• PHP ^8.1
• Laravel 10
• A reachable Docker Engine API endpoint (the host running the scans)

Installation

composer require ikay/theharvester-service

Publish and run the migrations:

php artisan vendor:publish --tag="theharvester-service-migrations"
php artisan migrate

Publish the config:

php artisan vendor:publish --tag="theharvester-service-config"

Configuration

The package talks to Docker over HTTP via a Guzzle client. Point it at your Docker Engine API in config/services.php:

'docker' => [
    'endpoint' => env('DOCKER_ENDPOINT', 'http://localhost:2375'),
    'timeout'  => env('DOCKER_TIMEOUT', 120),
],

config/theharvester-service.php controls how the package integrates with your app:

| Key | Default | Purpose | | --- | --- | --- | | model | User::class | The user model tasks belong to | | log_model | UserActivityLog::class | Model used for activity logging | | guard | web | Auth guard | | middleware | ['web'] | Middleware applied to routes | | auth_middleware | auth | Auth middleware | | layouts | layouts.master | Blade layout for the views | | theharvester_route | /tasks/theharvesters/ | Base route | | theharvester_index | /tasks/theharvesters | Index route |

How it works

A Theharvester task holds the scan request (domain, container count, title, description, status, user_id). Running it:

1. Creates container Docker containers from the secsi/theharvester:latest image, each running theHarvester -d <domain> -b all.
2. Starts them, waits for the scans to run, then stops them.
3. Streams each container's logs and parses them for IPs found, Emails found, and Hosts found.
4. Records the run time and result counts against the task, and marks its status.

Errors are captured to an error-log relation and to the single log channel, so a failed Docker call or scan is stored rather than thrown away.

Usage

use Ikay\TheharvesterService\Models\Theharvester;
use Ikay\TheharvesterService\TheharvesterService;

$task = Theharvester::create([
    'user_id'     => auth()->id(),
    'title'       => 'example.com recon',
    'domain'      => 'example.com',
    'container'   => 2,          // number of parallel scan containers
    'description' => 'Quarterly OSINT sweep',
    'status'      => 0,
]);

(new TheharvesterService($task))->createTheharvesterContainer();

// Results are stored on the task's container records:
$task->containers; // each has ip, email, host, operation_time, container_id

A TaskTheharvesterCreated event is dispatched when a task is created, so you can queue the scan from a listener rather than running it inline.

Data model

• Theharvester — a scan task. hasMany containers, hasMany error logs, belongsTo the configured user model.
• TheharvesterContainer — one container run: ip, email, host counts, operation_time, container_id.
• TheharvesterEventualError — captured exceptions (message, code, file, line, trace).

Testing

composer test

Security

This package executes Docker commands and runs OSINT tooling against domains you supply. Only run it against domains you are authorised to assess, and keep the Docker Engine endpoint on a trusted network — an exposed Docker API is a remote-code-execution risk.

License

MIT. See LICENSE.md.