Integrate Deft.

Quick Start

Get scanning in under a minute. All you need is an API key and a target domain.

curl -X POST https://deft.is/api/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

{
  "id": "d4f7a1b2-3c4e-5f6a-7b8c-9d0e1f2a3b4c",
  "domain": "example.com",
  "status": "running",
  "scan_type": "quick",
  "created_at": "2026-02-08T12:00:00Z"
}

curl https://deft.is/api/v1/scans/d4f7a1b2-3c4e-5f6a-7b8c-9d0e1f2a3b4c/results \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "d4f7a1b2-3c4e-5f6a-7b8c-9d0e1f2a3b4c",
  "domain": "example.com",
  "status": "completed",
  "created_at": "2026-02-08T12:00:00Z",
  "completed_at": "2026-02-08T12:02:30Z",
  "results": {
    "open_ports": [22, 80, 443, 3306],
    "services": [
      {"port": 22, "service": "ssh", "version": "OpenSSH 8.9"},
      {"port": 80, "service": "http", "version": "nginx/1.24.0"},
      {"port": 443, "service": "https", "version": "nginx/1.24.0"},
      {"port": 3306, "service": "mysql", "version": "MySQL 8.0.35"}
    ],
    "subdomains": ["api.example.com", "staging.example.com", "mail.example.com"],
    "vulnerabilities": [
      {
        "id": "CVE-2024-1234",
        "severity": "high",
        "cvss": 8.1,
        "service": "nginx/1.24.0",
        "description": "HTTP/2 rapid reset vulnerability"
      }
    ],
    "score": 72,
    "email_security": { ... },
    "security_headers": { ... },
    "summary": "AI-generated security assessment..."
  }
}

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are scoped to your organization and can be managed from the dashboard.

curl https://deft.is/api/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Scan

Initiate a new scan against a target domain. The scan runs asynchronously — poll the results endpoint or configure a webhook in your dashboard to be notified on completion.

Request body

curl -X POST https://deft.is/api/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "scan_type": "full"
  }'

Get Results

Retrieve the results of a completed scan. Returns open ports, discovered services, subdomains, vulnerabilities, and a composite security score.

Response fields

curl https://deft.is/api/v1/scans/d4f7a1b2-3c4e-5f6a-7b8c-9d0e1f2a3b4c/results \
  -H "Authorization: Bearer YOUR_API_KEY"

Code Scanning in CI

Create an Enterprise API key with code-scans:read and code-scans:write in Dashboard → API Keys. Add the repository in Code Scanning and configure its model connection first. Store DEFT_API_KEY and DEFT_FORGE_ACCESS_TOKEN as masked and protected CI variables. DEFT_API_KEY authorizes Deft API calls. DEFT_FORGE_ACCESS_TOKEN is a GitLab project or group token with read_api and read_repository scopes and Reporter access or higher; it replaces personal OAuth for CI scans.

The client reads CI_PROJECT_URL automatically and matches the GitLab host and full project path against tracked repositories in your organization. No DEFT_REPO_ID is needed. POST /api/v1/code-scans with repo_url, commit_sha, Idempotency-Key and X-Deft-Forge-Access-Token starts a full scan of that exact commit. GET /api/v1/code-scans/:id returns the gate. Use a new idempotency key for a new run; retry the same request with the same key after a network interruption.

All active medium, high and critical findings fail the gate, including existing findings and those with an open change request. Low and informational findings pass. Failed, cancelled, incomplete or timed-out scans fail the CI job. Fix availability and manual review decisions do not change this policy. CI scans do not create change requests or replace the repository baseline.

Use the published CI image; no script or repository checkout is needed in the job. Add security before deployment in your existing stages list. Jobs using needs must depend on this gate, and deployment rules must match its protected branch/tag policy.

deft_security:
  stage: security
  image:
    name: registry.gitlab.com/deftis/deft-ci:1.0.2
    entrypoint: [""]
  allow_failure: false
  timeout: 35m
  variables:
    GIT_STRATEGY: none
    DEFT_TIMEOUT_SECONDS: "1800"
  rules:
    - if: '$CI_COMMIT_REF_PROTECTED == "true"'
  before_script: []
  after_script: []
  cache: []
  dependencies: []
  script:
    - deft-code-scan
  artifacts:
    when: always
    paths:
      - deft-scan-result.json

The client reads CI_COMMIT_SHA and CI_PIPELINE_ID automatically and waits up to 30 minutes by default. Exit codes: 0 = passed, 1 = medium+ findings, 2 = operational error. A repository already scanning is retried within this deadline. GET limits: 120/minute; POST limits: 60/minute, shared per organization. The worker retrieves code using the technical GitLab token; the CI job only calls Deft APIs. The token is encrypted per run for worker recovery and cleared when analysis finishes. There is no personal-token fallback. Unsupported fork commits fail closed. Protected secrets are available only to eligible pipelines; never expose the key to untrusted forks.

Webhooks

Receive scan results automatically when a scan completes or fails. Configure webhook URLs in your dashboard under Settings > Webhooks. Deft sends a POST request to your configured URL with the full scan results payload.

Webhook payload

{
  "event": "scan.completed",
  "scan_id": "d4f7a1b2-3c4e-5f6a-7b8c-9d0e1f2a3b4c",
  "domain": "example.com",
  "timestamp": "2026-02-08T12:05:00Z",
  "results": {
    "open_ports": [22, 80, 443],
    "services": [...],
    "subdomains": [...],
    "vulnerabilities": [...],
    "score": 72
  }
}

# Example header value
X-Deft-Signature: sha256=a1b2c3d4e5f6...
X-Deft-Event: scan.completed

Service Discovery

TCP SYN scanning across the top 1,000 ports captures ~93% of services in enterprise environments. Each open port undergoes service fingerprinting to identify applications, versions, and protocols.

Attack Surface Mapping

Multi-source subdomain enumeration combining Certificate Transparency logs, passive DNS databases, and DNS zone analysis. Every discovered subdomain undergoes the same scanning pipeline as the primary domain.

Vulnerability Detection

Correlates discovered services against the NIST NVD and supplementary threat intelligence feeds. Findings are scored with CVSS v3.1 and enriched with exploit availability data.

Security Assessment

Composite security scoring that aggregates vulnerability density, service exposure, asset sprawl, and configuration hygiene. Reports include executive summary, technical findings, remediation guidance, and compliance mapping.