Skip to main content
Version: v0.21

PHP SDK Safety and State

The SDK reads untrusted project files and can change them when remediation is enabled. Treat a scan as a privileged operation with an explicit target, controlled storage, and a review path for every finding.

Process-global configuration​

Scanner stores its configuration and current report in static state. Fluent setters return a new Scanner instance, but they modify that shared process state.

$first = new Scanner();
$second = $first->setPathScan('/srv/project-a');

// Both objects observe the same Scanner configuration.

Run one scan at a time in each PHP process. Use a new CLI process for background jobs, concurrent requests, or tenant isolation. A long-lived worker must apply the complete configuration before each run and avoid reusing state from a prior job.

run() resets the report at the start of a scan. It does not reset the broader scanner configuration. Do not rely on object construction to restore defaults.

File actions​

The default prompt behavior differs between interactive and silent runs. Choose an action explicitly in unattended code:

$report = (new Scanner())
    ->setPathScan('/srv/app')
    ->setSilentMode()
    ->setAutoSkip()
    ->run();

For any action that changes files, call enableBackups() and set setPathBackups() to a writable directory outside the target. Keep quarantine, whitelist, deobfuscation, reports, logs, durable findings, and checkpoints outside the scanned project so the scanner does not inspect its own output.

Before enabling automatic clean, quarantine, or delete:

  1. Run report-only scans against representative copies of the application.
  2. Check coverage, findings, and diagnostics for each run.
  3. Test backup and restore procedures under the same account that runs production scans.
  4. Keep the target path constrained to approved project roots.

Paths and permissions​

Pass absolute paths from trusted configuration. Normalize and authorize request-derived paths before calling setPathScan(), setPathReport(), or any other path setter. The SDK normalizes paths with Path::get(), but normalization does not enforce your application's authorization boundary.

Run the scanner with the least filesystem access needed to read the target and write its controlled output. Do not run a web request as an account that can scan or delete files outside the intended deployment root.

Network behavior and offline operation​

Core code scanning uses embedded definitions. Integrity verification and Maltrail domain definitions can use outbound HTTPS. The scanner stores successful remote data in an operating-system cache outside the scan target.

When your environment blocks outbound traffic, capture and retain report diagnostics. A failed update can leave cached definitions active; the report records available metadata in signature_indexes. Do not assume an empty diagnostics array when no network route exists.

Failure policy​

Treat false from run() as an operational error. Treat incomplete coverage, diagnostics, and warnings as review signals. Store the report with its scan timestamp, target identity, scanner version from Scanner::getVersion(), and any external job identifier.

The SDK surfaces caught error messages through getLastError(). Log them in a protected application log. Do not expose target paths, report contents, or raw error text to untrusted users.