By Brute Logic
Research & Development in Offensive Security.

 
Back to Top
g

API Guidelines

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 other reason, you can simply generate a new one with the same process above.

 

 

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

 

Advanced Filter Bypass (AFB) - afb

Provide the value 1 to afb field to enable KNOXSS AFB.

 

afb=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.

 

Usage Examples

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

 

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.

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.