Submitting Scans

The Scan API accepts scan requests via a single, unified endpoint. Specify the target, scan engine, and optional configuration — the platform handles queuing, execution, result collection, and notifications.

Architecture

Scans are processed asynchronously via Kafka:

POST /scans → Kafka → Scan Engine → Results → Webhook/Polling

When you submit a scan, it's immediately queued and returns a scan ID. The scanner picks it up, executes it, and publishes results. You can poll the status or configure webhooks for real-time updates.

Create a Scan

Endpoint

POST /api/v1/scans

Required scope: scans:create

Request

curl -X POST https://api.cert-ix.com/scan-api/api/v1/scans \
  -H "X-API-Key: $CERTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "example.com",
    "scanType": "nmap",
    "name": "Weekly network audit",
    "targetType": "domain",
    "priority": "normal",
    "options": {
      "ports": "1-1024",
      "timing": "T3"
    },
    "tags": ["production", "weekly"],
    "timeout": 3600
  }'

Request Parameters

Field	Type	Required	Description
target	string	Yes	Scan target (URL, host, domain, IP, or CIDR)
scanType	string	Yes	Scan engine to use (see engine reference below)
name	string	No	Human-readable scan name
targetType	string	No	Target classification: host, url, domain, ip, network
priority	string	No	Execution priority: critical, high, normal, low (default: normal)
options	object	No	Engine-specific scan options
config	object	No	Engine-specific configuration overrides
tags	string[]	No	Custom tags for organization and filtering
timeout	integer	No	Max scan duration in seconds
assetId	string	No	Link scan to a registered asset in Asset Management
callbackUrl	string	No	HTTPS URL for one-off completion callback

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "scanType": "nmap",
    "name": "Weekly network audit",
    "target": "example.com",
    "status": "queued",
    "priority": "normal",
    "progress": 0,
    "tags": ["production", "weekly"],
    "createdAt": "2026-03-06T10:00:00Z"
  }
}

---

Scan Engine Reference

Nmap — Network Discovery

Type: nmap · Category: Network · Targets: host, ip, network, domain

Performs host discovery, port scanning, service detection, and OS identification. Ideal for network infrastructure assessments.

{
  "target": "192.168.1.0/24",
  "scanType": "nmap",
  "options": {
    "ports": "1-65535",
    "timing": "T4",
    "serviceDetection": true,
    "osDetection": true,
    "scriptScan": true,
    "scripts": ["vuln", "safe"]
  }
}

Option	Type	Default	Description
ports	string	1-1024	Port range (e.g., 22,80,443, 1-1024, 1-65535)
timing	string	T3	Timing template: T0 (paranoid) to T5 (insane)
serviceDetection	boolean	true	Enable service/version detection (-sV)
osDetection	boolean	false	Enable OS identification (-O)
scriptScan	boolean	false	Enable NSE script scanning
scripts	string[]	[]	NSE script categories to run
udpScan	boolean	false	Include UDP scanning (-sU)
topPorts	integer	—	Scan only top N most common ports

---

ZAP — Web Application Security

Type: zap · Category: Web App · Targets: url

OWASP ZAP performs Dynamic Application Security Testing (DAST). It spiders the target web application and tests for OWASP Top 10 vulnerabilities including XSS, SQL injection, CSRF, and more.

{
  "target": "https://app.example.com",
  "scanType": "zap",
  "options": {
    "scanPolicy": "full",
    "spiderMaxDepth": 5,
    "ajaxSpider": true,
    "activeScan": true,
    "contextInclude": ["https://app.example.com/.*"],
    "contextExclude": ["https://app.example.com/logout"]
  }
}

Option	Type	Default	Description
scanPolicy	string	standard	Scan intensity: light, standard, full
spiderMaxDepth	integer	3	Maximum spidering depth
ajaxSpider	boolean	false	Enable AJAX/JavaScript spider
activeScan	boolean	true	Perform active vulnerability testing
contextInclude	string[]	[]	Regex URL patterns to include in scope
contextExclude	string[]	[]	Regex URL patterns to exclude from scope
authentication	object	—	Authentication configuration (form, header, or cookie-based)

---

Trivy — Container Vulnerability Scanning

Type: trivy · Category: Container/Infrastructure · Targets: url, host

Scans container images, filesystems, and infrastructure-as-code for known vulnerabilities (CVEs), misconfigurations, and exposed secrets.

{
  "target": "registry.example.com/myapp:latest",
  "scanType": "trivy",
  "options": {
    "scanners": ["vuln", "misconfig", "secret"],
    "severity": ["CRITICAL", "HIGH"],
    "ignoreUnfixed": true
  }
}

Option	Type	Default	Description
scanners	string[]	["vuln"]	Scanners: vuln, misconfig, secret, license
severity	string[]	["CRITICAL","HIGH","MEDIUM"]	Filter by severity
ignoreUnfixed	boolean	false	Skip vulnerabilities without available fixes
skipDirs	string[]	[]	Directories to skip
skipFiles	string[]	[]	Files to skip

---

Nuclei — Template-Based Detection

Type: nuclei · Category: Vulnerability Detection · Targets: url, host, domain

Uses community and custom templates to detect vulnerabilities, misconfigurations, and exposures across a wide range of technologies.

{
  "target": "https://api.example.com",
  "scanType": "nuclei",
  "options": {
    "templates": ["cves", "vulnerabilities", "misconfigurations"],
    "severity": ["critical", "high", "medium"],
    "concurrency": 25,
    "rateLimit": 150
  }
}

Option	Type	Default	Description
templates	string[]	["cves"]	Template categories to run
severity	string[]	All	Filter by severity
concurrency	integer	25	Parallel template executions
rateLimit	integer	150	Max requests per second
tags	string[]	[]	Run only templates matching these tags
excludeTags	string[]	[]	Skip templates matching these tags

---

Nikto — Web Server Scanning

Type: nikto · Category: Web Server · Targets: url

Tests web servers for dangerous files, outdated software, and misconfigurations. Checks over 6,700 potentially dangerous files/CGIs.

{
  "target": "https://www.example.com",
  "scanType": "nikto",
  "options": {
    "tuning": "1234",
    "maxTime": "600s",
    "ssl": true
  }
}

Option	Type	Default	Description
tuning	string	"123"	Test categories: 1=Files, 2=Misconfigs, 3=Info, 4=XSS, etc.
maxTime	string	—	Max scan duration (e.g., "600s", "10m")
ssl	boolean	auto	Force SSL mode

---

SQLMap — SQL Injection Detection

Type: sqlmap · Category: Web App · Targets: url

Automates detection and exploitation of SQL injection flaws. Supports all major database engines.

{
  "target": "https://app.example.com/search?q=test",
  "scanType": "sqlmap",
  "options": {
    "level": 3,
    "risk": 2,
    "technique": "BEUSTQ",
    "dbs": true,
    "batch": true
  }
}

Option	Type	Default	Description
level	integer	1	Test level (1–5). Higher = more payloads
risk	integer	1	Risk level (1–3). Higher = more aggressive
technique	string	"BEUSTQ"	Injection techniques to test
dbs	boolean	false	Enumerate databases
batch	boolean	true	Non-interactive mode

Production Safety

SQLMap can be aggressive. Always use level ≤ 3 and risk ≤ 2 on production systems. Use higher values only in isolated test environments.

---

Wapiti — Web Application Scanning

Type: wapiti · Category: Web App · Targets: url

Performs black-box web application vulnerability scanning. Crawls the web application, identifies attack surfaces, and launches targeted tests.

{
  "target": "https://app.example.com",
  "scanType": "wapiti",
  "options": {
    "modules": ["xss", "sql", "exec", "file", "crlf"],
    "scope": "domain",
    "maxDepth": 5
  }
}

Option	Type	Default	Description
modules	string[]	All	Attack modules to enable
scope	string	"domain"	Crawl scope: url, page, folder, domain
maxDepth	integer	3	Maximum crawl depth
maxTime	string	—	Max scan duration

---

theHarvester — OSINT Reconnaissance

Type: harvester · Category: OSINT · Targets: domain

Collects email addresses, subdomains, IPs, and metadata from public sources. Passive reconnaissance that doesn't interact directly with the target.

{
  "target": "example.com",
  "scanType": "harvester",
  "options": {
    "sources": ["google", "bing", "linkedin", "shodan", "crtsh"],
    "limit": 500,
    "dnsLookup": true
  }
}

Option	Type	Default	Description
sources	string[]	All public	Data sources to query
limit	integer	200	Max results per source
dnsLookup	boolean	false	Perform DNS resolution of discovered hosts
dnsBrute	boolean	false	Enable DNS brute-force subdomain discovery

---

Sublist3r — Subdomain Enumeration

Type: sublist3r · Category: OSINT · Targets: domain

Enumerates subdomains using multiple search engines and DNS services. Discover your full attack surface.

{
  "target": "example.com",
  "scanType": "sublist3r",
  "options": {
    "engines": ["google", "bing", "yahoo", "virustotal", "dnsdumpster"],
    "bruteforce": true,
    "ports": "80,443,8080,8443",
    "threads": 30
  }
}

Option	Type	Default	Description
engines	string[]	All	Search engines to use
bruteforce	boolean	false	Enable DNS brute force
ports	string	—	Scan discovered subdomains for open ports
threads	integer	10	Concurrent threads

---

Sentinel — Multi-Engine Orchestration

Type: sentinel · Category: Unified/Comprehensive · Targets: url, host, domain, ip

Cert-IX's proprietary multi-engine orchestrated scan. Automatically selects and runs the most appropriate combination of scanners based on target type, then correlates and deduplicates findings into a unified report.

{
  "target": "example.com",
  "scanType": "sentinel",
  "priority": "high",
  "options": {
    "depth": "standard",
    "engines": ["nmap", "nuclei", "harvester", "sublist3r"],
    "correlate": true,
    "riskScore": true
  }
}

Option	Type	Default	Description
depth	string	"standard"	Assessment depth: quick, standard, deep
engines	string[]	auto	Specific engines to include (default: auto-select)
correlate	boolean	true	Correlate findings across engines
riskScore	boolean	true	Calculate aggregated risk score

Depth Levels:

Depth	Engines Used	Estimated Duration
quick	Nmap + Nuclei	5–15 minutes
standard	Nmap + Nuclei + Harvester + ZAP/Nikto	15–45 minutes
deep	All applicable engines	1–3 hours

---

Priority Levels

Priority affects queue ordering. Higher priority scans are processed first.

Priority	Queue Behavior	Use Case
critical	Front of queue, immediate processing	Active incident response
high	Ahead of normal scans	Pre-deployment checks
normal	Standard FIFO ordering	Routine assessments (default)
low	Processed when capacity available	Background/batch scans

Target Types

Target Type	Example Formats	Compatible Engines
host	server1.example.com	nmap, nuclei, sentinel
url	https://app.example.com/path	zap, nikto, sqlmap, wapiti, nuclei, trivy, sentinel
domain	example.com	nmap, nuclei, harvester, sublist3r, sentinel
ip	192.168.1.1, 2001:db8::1	nmap, nuclei, sentinel
network	192.168.1.0/24	nmap

Auto-Detection

If you omit targetType, the API infers it from the target format. Explicit typing is recommended for clarity.

Cancel a Scan

Cancel a running or queued scan:

POST /api/v1/scans/:scanId/cancel

Required scope: scans:cancel

curl -X POST "https://api.cert-ix.com/scan-api/api/v1/scans/$SCAN_ID/cancel" \
  -H "X-API-Key: $CERTIX_API_KEY"

List Scans

GET /api/v1/scans

Required scope: scans:list

Parameter	Type	Default	Description
scanType	string	nmap	Filter by scan engine
status	string	—	Filter by status
page	integer	1	Page number
limit	integer	20	Results per page (max: 100)

---

Next Steps:

• Scan Results & Status →
• Scan Templates →
• Webhooks →