canonical: https://jentic.com/apis/patrowl.local/patrowl # Patrowl Engines API The Patrowl Engines API provides a REST interface for controlling security scanning engines including Nmap, SSLLabs, Arachni, VirusTotal, and others. It exposes 14 endpoints for starting scans, checking scan status, retrieving findings, and managing engine configuration. Each engine instance runs as a separate service on a dedicated port and follows the same standardized API contract for scan lifecycle management. ## For AI agents Control Patrowl security scanning engines to start vulnerability scans, check scan progress, retrieve findings, and manage engine configurations across Nmap, SSLLabs, Arachni, and other scanners. ## Scope Does not handle vulnerability remediation, compliance reporting, or asset inventory - use for scan execution, status monitoring, and finding retrieval only. ## Capabilities - Initiate security scans against target hosts using multiple engine types - Monitor scan execution status and retrieve progress updates by scan ID - Retrieve structured vulnerability findings after scan completion - Manage engine lifecycle including configuration reloads and scan cleanup - Stop individual scans or halt all running scans on an engine - Check engine health through liveness and readiness probe endpoints - Clean scan data and temporary files after processing results ## Use cases ### Automated Vulnerability Scanning Initiate security scans against target hosts or networks using the /startscan endpoint. Patrowl engines support various scan types including port scanning (Nmap), SSL certificate analysis (SSLLabs), web application scanning (Arachni), and DNS reconnaissance (Owl DNS). Each scan receives a unique ID for status tracking and result retrieval. Example prompt: Start a scan via POST /startscan with target 'example.com' and scan type 'nmap_portscan', then poll GET `/status/{scanId}` until completion ### Security Findings Collection Retrieve structured vulnerability findings after scan completion through the `/getfindings/{scanId}` endpoint. Findings include severity levels, affected hosts, vulnerability descriptions, and remediation guidance. This enables automated security reporting, vulnerability tracking, and integration with ticketing systems for remediation workflows. Example prompt: Retrieve findings from scan ID 'scan_456' via GET `/getfindings/{scanId}` and extract all findings with severity 'high' or 'critical' ### Engine Health Monitoring Monitor scanning engine availability and readiness using the /liveness and /readiness endpoints. These health checks verify that the engine process is running and capable of accepting new scans. This supports orchestration platforms that need to route scan requests to healthy engine instances. Example prompt: Check engine health via GET /liveness and GET /readiness, then retrieve engine info via GET /info to confirm available scan capabilities ### AI Agent Security Scan Orchestration AI agents orchestrate security scans through Jentic by discovering scan operations, initiating scans against targets, and collecting findings without managing engine connectivity directly. Agents search for security scanning operations and receive structured schemas for the standardized Patrowl engine interface. Example prompt: Search Jentic for 'start a vulnerability scan', load the schema for POST /startscan, execute against target 'test.example.com', then retrieve findings via GET `/getfindings/{scanId}` ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/startscan` | Initiate a new security scan | | GET | `/status/{scanId}` | Check scan progress by ID | | GET | `/getfindings/{scanId}` | Retrieve scan findings | | GET | `/stop/{scanId}` | Stop a running scan | | GET | `/liveness` | Engine liveness health check | | GET | `/readiness` | Engine readiness check | | GET | `/info` | Get engine information and capabilities | | GET | `/clean/{scanId}` | Clean scan data by ID | ## Key resources - **Scans** — Start, stop, and monitor security scan execution - **Findings** — Retrieve vulnerability findings from completed scans - **Engine** — Check engine status, info, and manage configuration - **Health** — Verify engine liveness and readiness for scan requests ## Why Jentic - **Setup:** Wiring Patrowl by hand means targeting the right engine host for each scanner (nmap, ssllabs, arachni and others each run on their own port), polling scan status, and pulling findings yourself. Through Jentic you install once, import the Patrowl Engines API from the API Directory, and your agent calls it. - **Permission scoping:** Patrowl puts the scan id in the URL path (`/getfindings/{scanId}`), so a rule can pin your agent to one scan: it can check status and read findings and nothing else. You choose the operations it may call, so stopping or cleaning a scan is not included unless you add it. - **Credential handling:** Patrowl engines run without authentication, and where a network-level credential is needed it is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'start a vulnerability scan against a host' or 'get findings for a scan', and Jentic returns the matching Patrowl operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Snyk API** — Developer-focused vulnerability scanning for code dependencies - **Rapid7 API** — Enterprise vulnerability management and penetration testing platform - **Detectify API** — External attack surface monitoring and web scanning ## FAQ ### What authentication does the Patrowl Engines API use? The Patrowl Engines API does not require authentication by default as it is designed to run on localhost. Security is managed at the network level by restricting access to the engine ports (5001-5014). When deploying in production, network-level access controls or a reverse proxy with authentication should be used. ### Which scanning engines does Patrowl support? Patrowl supports multiple scanning engines each running on dedicated ports: Nmap (port 5001) for port scanning, SSLLabs (5004) for SSL analysis, Arachni (5005) for web application scanning, Owl DNS (5006) for DNS reconnaissance, VirusTotal (5007) for malware checks, URLVoid (5008) for URL reputation, Cortex (5009) for threat intelligence, and several others. ### How do I retrieve vulnerability findings from a scan? After starting a scan via POST /startscan, poll GET `/status/{scanId}` until the scan status shows completion. Then retrieve structured findings via GET `/getfindings/{scanId}.` Findings include severity level, affected target, description, and remediation guidance. Results can be cleaned after processing via GET `/clean/{scanId}.` ### Can I stop a running scan? Yes. Individual scans can be stopped via GET `/stop/{scanId}` using the scan ID returned when the scan was started. To stop all running scans on an engine, use GET /stopscans. Partially completed scans may still have findings available via the getfindings endpoint. ### How do I start a security scan through Jentic? Search Jentic for 'start a security vulnerability scan', load the operation schema for POST /startscan, and execute with target and scan configuration parameters. Jentic handles the engine routing and returns structured findings. Install with pip install jentic. ### What is the difference between liveness and readiness endpoints? GET /liveness confirms the engine process is running and responsive. GET /readiness confirms the engine is configured and capable of accepting new scan requests. An engine may be alive but not ready if it is still loading configuration or has reached maximum concurrent scan capacity. ### Can I limit what my agent is allowed to do with the Patrowl Engines API? Yes. Because you run Jentic One yourself, your own rules decide which Patrowl operations and credentials your agent can use. Since Patrowl puts the scan ID in the URL path, such as GET `/getfindings/{scanId}` and GET `/status/{scanId}`, you can pin an agent to a single scan so it only checks status and reads findings. Destructive operations like GET `/stop/{scanId}` or GET `/clean/{scanId}` stay out of reach unless you explicitly grant them.