On-Prem Scanners

Ostorlab supports on-premise scanning by deploying an Ostorlab scanner on user-controlled infrastructure. Depending on your license, you can run scans on mobile applications, Web/APIs, and private networks.

Following are the steps needed to run scans on-premise.

Go to report.ostorlab.co

1. Declare Scanner

Click the menu button in the top navigation bar to open the navigation drawer.

Click Scanning to expand the scanning section.

And choose Scanners.

To declare a new scanner, click on Add and select Add Scanner.

Fill in the Scanner name and description (and optionally assign it to an existing Scanner Group).

Save the scanner-identifier of your scanner (you can copy it directly using the copy icon in the table). Initially, the scanner will appear with an Offline status until the scanning daemon connects. This identifier will be used when launching the Ostorlab scanning daemon.

Optional: Scanner Groups (Parallel Execution & High Availability)

On the same Scanners page, you can organize multiple scanner nodes into Scanner Groups by switching to the Scanner Groups tab or choosing Add Scanner Group.

Fill in the group name, description, and select the scanner nodes to include in the group.

Why use Scanner Groups?
A scan creates multiple universes (sub-tasks and agent environments). With a single scanner node, scan universes wait in line and execute sequentially one after the other by default (though a single node can process universes concurrently if configured with --parallel N). With a Scanner Group, scan universes are distributed and processed simultaneously across all scanner nodes in the group. For example, grouping 2 scanners doubles processing throughput across machines; with enough scanners (greater than or equal to the number of universes), all universes run simultaneously for horizontal scaling, high availability, and the fastest possible scan completion.

2. Install and Authenticate the Scanner

Install the ostorlab CLI tool on the target machine with the scanner extras (ostorlab[scanner]), which includes python-daemon and psutil required to run the scanning daemon. Note that the scanner daemon is supported on Linux and macOS (Unix systems; Windows is not currently supported as the daemon relies on Unix process mechanics). Please also note that Ostorlab exclusively supports Python 3.13+ (>=3.13); older Python versions (such as Python 3.11) are deprecated and no longer supported. For more details, follow the instructions on the Ostorlab GitHub repository.

pip install --upgrade "ostorlab[scanner]"

Next, create an Organization API Key for authentication. Navigate to Integrations/API → API Keys in the left sidebar, click New API Key, specify a name, set the Role to Admin, and generate your API key. For detailed steps, refer to the Organization API Key documentation.

Run the scanner daemon on your machine using your Organization API key and the scanner identifier obtained earlier:

ostorlab --api-key=XXXX.XXXXXXX scanner --scanner-id=XXXX-XXXX-XXXXX

Tip

By default, the scanner executes one universe at a time (--parallel 1). You can increase concurrency on a single machine by passing --parallel N (e.g., --parallel 2).

Once connected, return to the Scanners page. The scanner status will update to Online (in green) with live system telemetry including IP address, CPU, and memory metrics:

3. Run a Scan

Now, to run a scan, head back to the Ostorlab platform and click on the menu button.

Click Scanning.

And choose New Scan.

Choose your asset type, e.g., Web App.

Fill in your targets (URLs or domains), and click Continue.

In the Scanner step, select either your individual scanner node or a Scanner Group to distribute the scan across multiple scanners, then click Continue.

Select the scan profile, e.g., Full Web Scan.

Configure additional settings or credentials if needed.

And click Submit.

The scan will be created and dispatched to your on-premise scanner (or distributed across the scanner nodes in your chosen Scanner Group).

This guide presented a comprehensive walk-through of on-premise scanning, spanning from the declaration of a scanner and scanner groups to running scans on designated infrastructure.