Create pentest draft

Create a draft pentest of repositories or uploaded archives, optionally with live sites

curl --request POST \
  --url https://api.hacktron.ai/v1/pentests \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "repos": [
    {
      "source": "connected",
      "url": "https://github.com/owner/repo",
      "branch": "<string>",
      "include_paths": [
        "services/gateway/**"
      ],
      "exclude_paths": [
        "**/tests/**",
        "vendor/",
        "*.md"
      ],
      "github_installation_id": 123
    }
  ],
  "target_urls": [
    "<string>"
  ],
  "custom_context": "<string>",
  "application_id": "<string>",
  "login_targets": [
    {
      "site": "<string>",
      "login_instructions": "<string>"
    }
  ]
}
'

import requests

url = "https://api.hacktron.ai/v1/pentests"

payload = {
    "repos": [
        {
            "source": "connected",
            "url": "https://github.com/owner/repo",
            "branch": "<string>",
            "include_paths": ["services/gateway/**"],
            "exclude_paths": ["**/tests/**", "vendor/", "*.md"],
            "github_installation_id": 123
        }
    ],
    "target_urls": ["<string>"],
    "custom_context": "<string>",
    "application_id": "<string>",
    "login_targets": [
        {
            "site": "<string>",
            "login_instructions": "<string>"
        }
    ]
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    repos: [
      {
        source: 'connected',
        url: 'https://github.com/owner/repo',
        branch: '<string>',
        include_paths: ['services/gateway/**'],
        exclude_paths: ['**/tests/**', 'vendor/', '*.md'],
        github_installation_id: 123
      }
    ],
    target_urls: ['<string>'],
    custom_context: '<string>',
    application_id: '<string>',
    login_targets: [{site: '<string>', login_instructions: '<string>'}]
  })
};

fetch('https://api.hacktron.ai/v1/pentests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hacktron.ai/v1/pentests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'repos' => [
        [
                'source' => 'connected',
                'url' => 'https://github.com/owner/repo',
                'branch' => '<string>',
                'include_paths' => [
                                'services/gateway/**'
                ],
                'exclude_paths' => [
                                '**/tests/**',
                                'vendor/',
                                '*.md'
                ],
                'github_installation_id' => 123
        ]
    ],
    'target_urls' => [
        '<string>'
    ],
    'custom_context' => '<string>',
    'application_id' => '<string>',
    'login_targets' => [
        [
                'site' => '<string>',
                'login_instructions' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hacktron.ai/v1/pentests"

	payload := strings.NewReader("{\n  \"repos\": [\n    {\n      \"source\": \"connected\",\n      \"url\": \"https://github.com/owner/repo\",\n      \"branch\": \"<string>\",\n      \"include_paths\": [\n        \"services/gateway/**\"\n      ],\n      \"exclude_paths\": [\n        \"**/tests/**\",\n        \"vendor/\",\n        \"*.md\"\n      ],\n      \"github_installation_id\": 123\n    }\n  ],\n  \"target_urls\": [\n    \"<string>\"\n  ],\n  \"custom_context\": \"<string>\",\n  \"application_id\": \"<string>\",\n  \"login_targets\": [\n    {\n      \"site\": \"<string>\",\n      \"login_instructions\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hacktron.ai/v1/pentests")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"repos\": [\n    {\n      \"source\": \"connected\",\n      \"url\": \"https://github.com/owner/repo\",\n      \"branch\": \"<string>\",\n      \"include_paths\": [\n        \"services/gateway/**\"\n      ],\n      \"exclude_paths\": [\n        \"**/tests/**\",\n        \"vendor/\",\n        \"*.md\"\n      ],\n      \"github_installation_id\": 123\n    }\n  ],\n  \"target_urls\": [\n    \"<string>\"\n  ],\n  \"custom_context\": \"<string>\",\n  \"application_id\": \"<string>\",\n  \"login_targets\": [\n    {\n      \"site\": \"<string>\",\n      \"login_instructions\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hacktron.ai/v1/pentests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"repos\": [\n    {\n      \"source\": \"connected\",\n      \"url\": \"https://github.com/owner/repo\",\n      \"branch\": \"<string>\",\n      \"include_paths\": [\n        \"services/gateway/**\"\n      ],\n      \"exclude_paths\": [\n        \"**/tests/**\",\n        \"vendor/\",\n        \"*.md\"\n      ],\n      \"github_installation_id\": 123\n    }\n  ],\n  \"target_urls\": [\n    \"<string>\"\n  ],\n  \"custom_context\": \"<string>\",\n  \"application_id\": \"<string>\",\n  \"login_targets\": [\n    {\n      \"site\": \"<string>\",\n      \"login_instructions\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "scan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "repos": [
    {
      "include_paths": [
        "services/gateway/**"
      ],
      "exclude_paths": [
        "**/tests/**",
        "vendor/",
        "*.md"
      ],
      "source": "connected",
      "provider": "github",
      "url": "https://github.com/owner/repo",
      "branch": "<string>",
      "ref_type": "branch",
      "archive_id": "<string>",
      "github_installation_id": 123
    }
  ],
  "target_urls": [
    "<string>"
  ],
  "login_targets": [
    {
      "site": "<string>",
      "login_check": "unverified",
      "failure_reason": "<string>"
    }
  ],
  "custom_context": "<string>",
  "application_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cost_estimation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "triage_enabled": true,
  "credits_used": 123
}

POST

pentests

Create a draft pentest of repositories or uploaded archives, optionally with live sites

curl --request POST \
  --url https://api.hacktron.ai/v1/pentests \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "repos": [
    {
      "source": "connected",
      "url": "https://github.com/owner/repo",
      "branch": "<string>",
      "include_paths": [
        "services/gateway/**"
      ],
      "exclude_paths": [
        "**/tests/**",
        "vendor/",
        "*.md"
      ],
      "github_installation_id": 123
    }
  ],
  "target_urls": [
    "<string>"
  ],
  "custom_context": "<string>",
  "application_id": "<string>",
  "login_targets": [
    {
      "site": "<string>",
      "login_instructions": "<string>"
    }
  ]
}
'

import requests

url = "https://api.hacktron.ai/v1/pentests"

payload = {
    "repos": [
        {
            "source": "connected",
            "url": "https://github.com/owner/repo",
            "branch": "<string>",
            "include_paths": ["services/gateway/**"],
            "exclude_paths": ["**/tests/**", "vendor/", "*.md"],
            "github_installation_id": 123
        }
    ],
    "target_urls": ["<string>"],
    "custom_context": "<string>",
    "application_id": "<string>",
    "login_targets": [
        {
            "site": "<string>",
            "login_instructions": "<string>"
        }
    ]
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    repos: [
      {
        source: 'connected',
        url: 'https://github.com/owner/repo',
        branch: '<string>',
        include_paths: ['services/gateway/**'],
        exclude_paths: ['**/tests/**', 'vendor/', '*.md'],
        github_installation_id: 123
      }
    ],
    target_urls: ['<string>'],
    custom_context: '<string>',
    application_id: '<string>',
    login_targets: [{site: '<string>', login_instructions: '<string>'}]
  })
};

fetch('https://api.hacktron.ai/v1/pentests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hacktron.ai/v1/pentests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'repos' => [
        [
                'source' => 'connected',
                'url' => 'https://github.com/owner/repo',
                'branch' => '<string>',
                'include_paths' => [
                                'services/gateway/**'
                ],
                'exclude_paths' => [
                                '**/tests/**',
                                'vendor/',
                                '*.md'
                ],
                'github_installation_id' => 123
        ]
    ],
    'target_urls' => [
        '<string>'
    ],
    'custom_context' => '<string>',
    'application_id' => '<string>',
    'login_targets' => [
        [
                'site' => '<string>',
                'login_instructions' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hacktron.ai/v1/pentests"

	payload := strings.NewReader("{\n  \"repos\": [\n    {\n      \"source\": \"connected\",\n      \"url\": \"https://github.com/owner/repo\",\n      \"branch\": \"<string>\",\n      \"include_paths\": [\n        \"services/gateway/**\"\n      ],\n      \"exclude_paths\": [\n        \"**/tests/**\",\n        \"vendor/\",\n        \"*.md\"\n      ],\n      \"github_installation_id\": 123\n    }\n  ],\n  \"target_urls\": [\n    \"<string>\"\n  ],\n  \"custom_context\": \"<string>\",\n  \"application_id\": \"<string>\",\n  \"login_targets\": [\n    {\n      \"site\": \"<string>\",\n      \"login_instructions\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hacktron.ai/v1/pentests")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"repos\": [\n    {\n      \"source\": \"connected\",\n      \"url\": \"https://github.com/owner/repo\",\n      \"branch\": \"<string>\",\n      \"include_paths\": [\n        \"services/gateway/**\"\n      ],\n      \"exclude_paths\": [\n        \"**/tests/**\",\n        \"vendor/\",\n        \"*.md\"\n      ],\n      \"github_installation_id\": 123\n    }\n  ],\n  \"target_urls\": [\n    \"<string>\"\n  ],\n  \"custom_context\": \"<string>\",\n  \"application_id\": \"<string>\",\n  \"login_targets\": [\n    {\n      \"site\": \"<string>\",\n      \"login_instructions\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hacktron.ai/v1/pentests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"repos\": [\n    {\n      \"source\": \"connected\",\n      \"url\": \"https://github.com/owner/repo\",\n      \"branch\": \"<string>\",\n      \"include_paths\": [\n        \"services/gateway/**\"\n      ],\n      \"exclude_paths\": [\n        \"**/tests/**\",\n        \"vendor/\",\n        \"*.md\"\n      ],\n      \"github_installation_id\": 123\n    }\n  ],\n  \"target_urls\": [\n    \"<string>\"\n  ],\n  \"custom_context\": \"<string>\",\n  \"application_id\": \"<string>\",\n  \"login_targets\": [\n    {\n      \"site\": \"<string>\",\n      \"login_instructions\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "scan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "repos": [
    {
      "include_paths": [
        "services/gateway/**"
      ],
      "exclude_paths": [
        "**/tests/**",
        "vendor/",
        "*.md"
      ],
      "source": "connected",
      "provider": "github",
      "url": "https://github.com/owner/repo",
      "branch": "<string>",
      "ref_type": "branch",
      "archive_id": "<string>",
      "github_installation_id": 123
    }
  ],
  "target_urls": [
    "<string>"
  ],
  "login_targets": [
    {
      "site": "<string>",
      "login_check": "unverified",
      "failure_reason": "<string>"
    }
  ],
  "custom_context": "<string>",
  "application_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cost_estimation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "triage_enabled": true,
  "credits_used": 123
}

Creates a draft with the code you want to review and any deployed sites you want to test. Creating a draft does not run a pentest or spend credits. You review the estimate before starting it.

Scope required: write. Role: member or above.

Set up and start a pentest

Create the draft with this endpoint, and change it with Update pentest draft.
If the draft has login_targets, run Check pentest logins until each login passes.
Get the credit cost with Estimate pentest.
Start it with Start pentest, or delete it with Discard pentest draft.

Save the scan_id from the response. Use the same ID throughout setup and after the pentest starts, including when calling Get scan.

What to test

repos (at least one): connected repositories, public repositories, or archives uploaded with Request archive upload. Set a repository’s include_paths and exclude_paths to review only part of the code.
target_urls: deployed sites to test without signing in.
login_targets: deployed sites to test signed in. Each has a site and login_instructions: the login page, username, password and any extra steps. Login instructions are stored encrypted and never returned.

A draft can have target_urls or login_targets, but not both. To test sites with and without a login, create separate pentests.

Signed-in testing is enabled per organization. If it isn’t enabled for yours, a request with login_targets returns 400.

Authorizations

X-Api-Key

string

header

required

Body

application/json

repos

object[]

required

Repositories or uploaded archives to test

Minimum array length: 1

Option 1
Option 2
Option 3

Show child attributes

target_urls

string[]

Target URLs (pentest only)

custom_context

string

Custom context (pentest only)

application_id

string

iva application this scan targets (group of repos)

Deployed sites to test signed in, each with how to sign in. On update the list replaces the saved one, and [] removes them. A pentest tests live sites either all signed in or all without a login (target_urls). Check each login with POST /pentests/{id}/login-checks before starting.

Maximum array length: 10

Show child attributes

Response

201 - application/json

scan_id

string<uuid>

required

Stable pentest id; task_id changes when it starts

status

enum<string>

required

Available options:

pending,

running,

completed,

failed,

stopped,

cancelled,

skipped,

pending_verification,

pending_triage,

draft,

estimating,

estimated

repos

object[]

required

Show child attributes

target_urls

string[]

required

Show child attributes

custom_context

string | null

required

application_id

string<uuid> | null

required

cost_estimation_id

string<uuid> | null

required

triage_enabled

boolean | null

required

credits_used

number | null

required

⌘I

Getting started

Cost Estimations

Scans

Pentests

Credits

Findings

Repositories

Dependency Firewall

Set up and start a pentest

What to test

Authorizations

Body

Response

​Set up and start a pentest

​What to test

Authorizations

Body

Response

Set up and start a pentest

What to test