The API

* KNOXSS API is only available to Pro users. If you have a demo account, upgrade to Pro in your dashboard to be able to get an API key. *

KNOXSS API is another way to query KNOXSS system if it can find and prove a XSS vulnerability in a given target page. Unlike other APIs that just retrieve data from a database, KNOXSS API returns the results like the web interface, actually performing a comprehensive vulnerability scan for XSS. Since scan results are not stored by our system, they need to be generated on the fly taking several JavaScript-evaluated live tests to return them. So it's natural the data returned takes much more time to get delivered since there's a long process involved at server side.

The API standard rate limit is 5000 requests over a 24 hours period. That means an average of 3.4 requests per minute so please try to keep this pace to not overload the system (or get blocked). As explained above, KNOXSS API is not like most APIs out there, the system needs time to process results for each API call with a scan in the background.

API Key

To use the KNOXSS API you need your API key: it must be sent to API endpoint with the header X-API-KEY.

Example:

X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6

Generating or Regenerating your API Key

The API key is in your profile. If you have never generated it you need to hit the button at least once to do it.

After that, hit the SAVE button.

* Don't forget this last step or you will get an "Invalid or expired API key" message. *

Any time you need a new API key for any reason, you can simply generate a new one with the same process above.

IMPORTANT - After the very first successful API call you must keep using the same API key until its counting resets (24hs), only after that you can generate a new one.

All requests to API must be done via POST method to the following endpoint:

https://knoxss.me/api/v3

https://api.knoxss.pro

API Request Data

Those are the data fields used to request to the API with their usage schemes.

Target (mandatory) - target

Target is the only mandatory field without it KNOXSS API can't test anything. Provide an URL in the format http(s)://domain/path/page with query string (?param1=value&param2=value&param3=value) or not.

target=https://domain/path/page?param1=value%26param2=value%26param3=value
target=https://domain/path/page

POST Body - post

Provide a POST body if your request is done via HTTP POST method (HTML forms) in the format param1=value&param2=value&param3=value with the action URL (without query string).

post=param1=value%26param2=value%26param3=value

Extra Header(s) for Authentication - auth

Provide a header needed to pass the request to test authenticated pages in the format header:value. Separate those pairs with CRLF characters (%0D%0A) if more than one header are needed.

auth=header:value
auth=header1:value%0D%0Aheader2:value

CheckPoC Feature - checkpoc

Provide the value 1 to checkpoc field to enable KNOXSS CheckPoC feature. More details about it in our FAQ.

checkpoc=1

Flash Mode Mark - [XSS]

Provide the [XSS] mark in any place of the target's data values to enable Flash Mode which enables KNOXSS to perform a single quick XSS Polyglot based test.

target=https://domain/path/page?param1=value[XSS]
target=https://domain/path/page?param1=[XSS]
target=https://domain/path/[XSS]?param1=value
post=param1=value[XSS]
post=param1=[XSS]
auth=header:[XSS]

*** IMPORTANT ***

It's needed to encode all "&" signs as %26 in URL parameters and POST bodies because the main "&" is used by curl to separate the parameters to the API, not target's.

API Response Data

Those are the data fields present in the API response, in that sequence.

XSS 

Possible values => "true", "false", "none"

It returns the result of the scan regarding the XSS status. If KNOXSS is able to prove a XSS vulnerability, this field will return "true". If not but the scan didn't get an error it will return "false". In case of an error, it will return "none".

PoC

Possible values => "[STRING]", "none"

It returns the PoC (Proof-of-Concept) in a [STRING] format for the XSS found when the "XSS" field returns "true". In case of "false" or "none, this field returns "none". Notice that in JSON format some characters are properly escaped (" and \) so don't just copy and paste this in a web browser without removing or adapting the escape sequences.

Target

Possible values => "[STRING]"

It just returns the target provided in a "[STRING]" format.

POST Data

Possible values => "[STRING]", "none"

It just returns the POST body provided in a "[STRING]" format or "none" in case it was not informed.

Error

Possible values => "[STRING]", "none"

It returns the error description if any or "none" if the scan performed properly.

API Call

Possible values => "n/5000", "0"

It returns the number of API calls (n) made so far in the last 24hs period (maximum 5000) since the last "expiration time reset" event. It returns "0" in case of an error.

Time Elapsed

Possible values => "[STRING]"

It returns the performance time of the scan in the "[x].[y]s" format where [x] is the number of seconds up to 3 place before comma and [y] is the number of milliseconds with 2 places after comma.

Timestamp

Possible values => "[STRING]"

It returns the date and time of the service in the end of scan.

Version

Possible values => "[STRING]"

It returns the version of the API.

API Request/Response Example

curl https://api.knoxss.pro -d "target=https://brutelogic.com.br/xss.php?a=any" -H "X-API-KEY: 5499f19d-e203-4758-82a7-ff6eb09233b9"

{

}

...

Usage Examples

Examples of usage with command-line curl (replace examples with your own API key):

IMPORTANT: use DOUBLE QUOTES in Windows systems instead of single ones.

GET Method - URL with 1 parameter

curl https://api.knoxss.pro -d 'target=https://brutelogic.com.br/xss.php?a=any' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

GET Method - URL with 2+ parameters

curl https://api.knoxss.pro -d 'target=https://brutelogic.com.br/xss.php?a=any%26b=any' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

=> Notice the %26 between "a=any" and "b=any" pairs of name/value.

POST Method - URL + POST data

curl https://api.knoxss.pro -d 'target=https://brutelogic.com.br/xss.php&post=a=any' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

=> Notice the &post= in the "-d" flag right at the end of the URL. It's posted as another parameter to the API, not a parameter of the target.

POST Method *** TestPHP VulnWeb ***

curl https://api.knoxss.pro -d 'target=http://testphp.vulnweb.com/search.php?test=query&post=searchFor=any%26goButton=go' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

=> Notice the &post= in the "-d" flag right at the end of the URL. It's posted as another parameter to the API, not a parameter of the target.

Authenticated GET Method - Cookies

curl https://api.knoxss.pro -d 'target=https://brutelogic.com.br/session/index.php?name=guest&auth=Cookie:PHPSESSID=9p77u90dssmkmn3kgmmgq3b5d3' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

=> Notice the &auth= in the "-d" flag right at the end of the URL. It's posted as another parameter to the API, not a parameter of the target.

AFB Enabled GET Method 

curl https://api.knoxss.pro -d 'target=https://brutelogic.com.br/tests/strip.php?user_name=tester&afb=1' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

=> Notice the &afb=1 in the "-d" flag right at the end of the URL. It's posted as another parameter to the API, not a parameter of the target.

Flash Mode - XSS Mark
Place the [XSS] mark where you want KNOXSS to make a super fast test with its XSS polyglot. It works for both GET and POST methods.

curl https://api.knoxss.pro -d 'target=https://brutelogic.com.br/xss.php?a=[XSS]' -H 'X-API-KEY: 93c864f5-af3a-4f6a-8b25-8662bc8b5ab6'

Mass Testing

There are some non-official wrappers publicly available to help with automation, most notably knoxnl (click).

Here's a simple Bash Script to automate the submission of a file with URLs to the API:


#!/bin/bash
file=$1
key="API_KEY"
while read line
do curl https://api.knoxss.pro -d target=$line -H "X-API-KEY: $key" -s | grep PoC
done < $file


• Copy and paste the code above in a txt file named "api.sh" (without quotes) then use "chmod +x api.sh" (without quotes) to make it executable.
• Replace "API-KEY" with your API Key keeping the quotes.
• Create a text file named "urls.txt" with 1 target page per line. That line must contain the whole "-d" argument for curl, including POST data e other directives separated by a "&" for features and "%26" for parameter separation like examples above.

Usage: ./api.sh urls.txt

Obs: that's a simple script meant to be shared via Twitter (X) and contains basic verbosity and functionalities.

Simple Bash Script
For mass testing with #KNOXSS API! 😀#XSS #BugBounty

#!/bin/bash
file=$1
key="API_KEY"
while read line
do curl https://knoxss .me/api/v3 -d target=$line - H "X-API-KEY: $key -s | grep PoC
done < $file

Usage: ./api.sh urls.txt
⬇️ pic.twitter.com/mov66ZGD1j

— KNOXSS (@KN0X55) September 5, 2023