Research Academy
My account Customers About Blog Careers Legal Contact Resellers

Burp Suite User Forum

Create new post

How to invoke a burp enterprise scan with extension from command line / jenkins CICD

Mathews, | Last updated: Dec 02, 2021 09:51PM UTC

Hello, Our organization has a burpsuite enterprise license. We are trying to invoke burp enterprise site (with custom configuration and extension) from jenkins or from REST API - POST screen. I have created a burp enterprise scan with an extension. I have uploaded the jar file for extension. I would like to invoke the scan with extension from jenkins job. 1. I installed jenkins plugin for burp. 2. I created the curl script from "http://<host>:<port>/api/<apikey>/v0.1/" . Given the "name" parameter in "POST rest API" as same as the site name created in burp enterprise. The site created in burp enterprise with extension. 3. Used the curl command in jenkins job. It will trigger the scan as a new instance. Its not considering the existing site that created with extensions. 4. I tried the same from POST Rest API screen and click "send request" button. It trigger scan as a new site even if we provide the same site name. How can i trigger the scan for the site created already in burp enterprise from jenkins or from command line? If its possible to trigger from command line then i can write a batch file or shell and invoke from jenkins. Is there any API utility available to trigger the scan for a site in burp enterprise? Please help.

James, PortSwigger Agent | Last updated: Dec 03, 2021 11:35AM UTC

Hi Dinse,

Thanks for getting in touch.

For triggering a scan in Burp Enterprise via the API, with a custom scan configuration and extension you have applied to the site, I would recommend using the Burp Enterprise GraphQL API, which includes more functionality. The REST API is quite limited.

You can convert the GraphQL query to curl if you wish. I would recommend using the free Insomnia tool to create the query as a GraphQL POST request and you can also easily convert this to curl using Insomnia.
https://insomnia.rest/download

1) New request > POST > GraphQL query

2) Enter the URL "YOUR-ENTERPRISE-SERVER-URL:PORT/graphql/v1"

3) Go to the "Header" tab > Add a new header called "Authorization" and enter the API key for the Burp Enterprise API user you have already set up
https://portswigger.net/burp/documentation/enterprise/administration-tasks/ci-cd/create-api-user

4) Build and test your query (example below)

5) Right click on the request from the left menu > Copy as curl


Below is an example request which will trigger a non-recurring scan to start instantly, specifying a custom scan configuration. For extensions, if you have applied these to the site in Burp Enterprise > Site details they will be applied to the scan automatically. (For scan configurations, you have to specify this even if default configurations are applied to the site. We are looking to change this next year).

Firstly you will want to fetch the list of "site_id" and "scan_configuration_ids" parameters you will need for your request.

GetSiteTree:
query GetSiteTree {
    site_tree {
        sites {
            id
            name
            parent_id
        }
    }
}
In this example lets say my "site_id" is "1".

GetScanConfigurations
query GetScanConfigurations {
  scan_configurations {
    id
    name
  }
}
In this example lets say my scan configuration ID for my custom configuration is "37791324-14be-41c5-807d-1ff99b8b4ea1".


GraphQL POST
mutation CreateScheduleItem($input:CreateScheduleItemInput!) {
create_schedule_item(input: $input) {
schedule_item {
id
}
}
}
Query variables
{
	"input": {
		"site_id": "1",
		"scan_configuration_ids": [
			"37791324-14be-41c5-807d-1ff99b8b4ea1"
		]
	}
}


The GraphQL POST converted to curl:
curl --request POST \
  --url YOUR-ENTERPRISE-SERVER-URL:8085/graphql/v1 \
  --header 'Authorization: YOUR-API-KEY' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation CreateScheduleItem($input:CreateScheduleItemInput!) {\ncreate_schedule_item(input: $input) {\nschedule_item {\nid\n}\n}\n}","variables":{"input":{"site_id":"1","scan_configuration_ids":["37791324-14be-41c5-807d-1ff99b8b4ea1"]}},"operationName":"CreateScheduleItem"}'
Relevant documentation is here:
https://portswigger.net/burp/documentation/enterprise/api-documentation
https://portswigger.net/burp/extensibility/enterprise/graphql-api/
https://portswigger.net/burp/extensibility/enterprise/graphql-api/create_schedule_item.html

Let me know if you need any further assistance.

Mathews, | Last updated: Dec 03, 2021 05:07PM UTC

Thanks for the response. Please help me out with some more details to finish this. I have API user and below URL is working : http://<host>:<port>/api/<API key>/v0.1/ . This URL is working and i am able to send request to scan. But when i give below URL as you suggested; am getting error. http://<host>:<port>/graphql/v1 {"errors":[{"message":"Unexpected exception occurred. Check logs for more details.","extensions":{"code":77}}]} I tried "server url/graphql/v0.1". This also not working What I want to do is to automate the DAST scan without any manual changes. I tried below URL from command line and its working. I need to change the scan_configurations dynamically. I will get scan_configuration from 'burp pro project options' and i can replace the value for scan_configurations programatically before trigger the curl command. But these scan_sconfigurations should apply for a site that already in burp enterprise since that site is associated with an extension. Thats the challenge now. curl http://<host>:<port>/api/<apikey>/v0.1/scan -d {\"scan_configurations\":[],\"urls\":[\"https://<url>\"]} Could you please help to provide a working graphql command that i can replace the site id and scan_configurations ? If i need to use scan_configuration id then i have to upload it in burp enterprise right? thats is a manual effort. Then it won't be fully automated. My use case is: When ever a test engineer complete a scan a site using burp pro, he will save the project options to a json file and check-in to a repository manually. Anytime a developer make changes and check-in the code to repository jenkins job will trigger the scan based on the previous project options on that site which is created already in burp enterprise. I am able to make it except the scan against the site-id which already in burp enterprise with extension. Could you please help to understand below steps ? 1) New request > POST > GraphQL query [ How to start new request? its from where we need to start? ] 2) Enter the URL "YOUR-ENTERPRISE-SERVER-URL:PORT/graphql/v1" [This URL not working and throws error] 3) Go to the "Header" tab > Add a new header called "Authorization" and enter the API key for the Burp Enterprise API user you have already set up https://portswigger.net/burp/documentation/enterprise/administration-tasks/ci-cd/create-api-user [I have API user and API key used for REST API section. Is the same API key can be used? Today i tried to create user and its not working. getting this error. Failed to create user: An unexpected error occurred. If this problem persists, please contact support@portswigger.net. But i am able to create API user. ] I think, unless i get "YOUR-ENTERPRISE-SERVER-URL:PORT/graphql/v1" working, i am not able to try any other options. Please help me to procced from here.

James, PortSwigger Agent | Last updated: Dec 06, 2021 09:12AM UTC

Hi Dinse, I have responded to the email you also sent in.

You must be an existing, logged-in customer to reply to a thread. Please email us for additional support.