Developer Documentation
The Tinfoil Security API is a RESTful API designed to help you programatically do all of the things you can do via our web application. It runs over HTTPS and uses HTTP token authentication to ensure that only you can see your data. All responses can either be returned in JSON (the default) or XML, and HTTP response codes are used for error conditions, such as a 404 for resources that could not be found and 401 for failure to authenticate. Any HTTP client should work well, like cURL.
JSON
$ curl https://www.tinfoilsecurity.com/api/v1/sites -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
XML
$ curl https://www.tinfoilsecurity.com/api/v1/sites.xml -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
LIST YOUR SITES
Request
GET /api/v1/sites
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Response
{ "total_pages":2, "page_number":1, "next_page":"https://www.tinfoilsecurity.com/api/v1/sites?page=2", "sites":[ { "site":{ "id":"example", "name":"Example Site", "url":"http://www.example.org", "request_rate":40, "auth_types":["saml", "basic"], "last_successful_scan":{ "id":"se1353116801559949000", "start_time":"2012-11-17T01:46:49Z", "end_time":"2012-11-17T02:06:47Z", "scan_type":"full", "status":"done" } } }, "..." ] }
Returns a list of all of the sites that you own or that are shared with you. Each site listing includes an ID
of the last successful scan so you can go straight to its report.
Parameters
per_page
- Optional (Default is 10). Use this to specify how many records are returned on each page.
page
- Optional (Default is 1). Use this to specify which page of records to view.
Response Description
total_pages
and page_number
let you know where you are in the list of sites, and next_page
provides you with a link to the next page of sites. If you are on the last page, the next_page
attribute will not be present.
auth_type
- zero or more of the following: form, javascript, custom_login_javascript, recorded_login, saml, basic, digest, ntlm, custom_login.
LIST YOUR PLANS
Request
GET /api/v1/plans
Example
$ curl https://www.tinfoilsecurity.com/api/v1/plans -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Response
[ { "plan":{ "id":1, "name":"Starter Plan" } }, { "plan":{ "id":2, "name":"Standard Plan" } }, { "plan":{ "id":3, "name":"All Access Plan" } } ]
Returns a list of all of the plans available for your sites. Each site listing includes an ID
of the plan that can be assigned to the site. Some plans (like those typically labeled "Free") may have other restrictions that need to be met before they can be assigned to a site. Assigning a plan to a site will update your billing invoice right away, and may result in additional charges. Please see your dashboard for more information.
ADD/UPDATE A SITE
Request
ADD:POST /api/v1/sites
UPDATE: PUT /api/v1/sites/:site_id/
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites -X POST -d 'site[name]=Example' -d 'site[url]=http://example.org' -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Success Response
HTTP Response Code: 201
{ "site": { "id": "example", "url": "http://example.org", "request_rate": 40 } }
Sample Failure Response
HTTP Response Codes: 403, 412
{ "errors": [ "You have reached the maximum number of sites allowed for this account." ] }
Creates or modifies an existing site profile for scanning. You must have full API access (not read-only) to perform this operation.
Parameters
site[name]
- Required.
site[url]
- Required.
site[plan_id]
- Optional, but required for scans to be able to run.
site[basic_auth_username]
- Optional.
site[basic_auth_password]
- Optional.
site[auth_url]
- Optional. The URL where a form with the inputs specified by auth_username_field and auth_password_field is expected to be found.
site[auth_username]
- Optional.
site[auth_username_field]
- Optional. The name attribute of a form input expecting the username.
site[auth_password]
- Optional.
site[auth_password_field]
- Optional. The name attribute of a form input expecting the password.
site[max_request_rate]
- Optional (default is 40). Value between 2 and 100.
site[audit_contact_forms]
- Optional. Boolean.
site[discover_unknown_paths]
- Optional. Boolean.
site[custom_headers]
- Optional. Object; keys are the header names, and values are the header values. Set custom headers to send along with every scan. Example: site[custom_headers][X-Custom-Tag]=#interesting-tag
schedule[frequency]
- Optional. One of "monthly", "weekly", "daily", "none".
schedule[scan_time_of_month]
- Optional. One of "1", "2", "3", "4". For Monthly schedules, represents the nth chosen day of the week the scan will occur on (eg. Setting scan_time_of_month to "4" and scan_time_of_week to "friday" would create a schedule that scans on the 4th Friday of each month)
schedule[scan_time_of_week]
- Optional. One of "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday". For Monthly or Weekly schedules.
schedule[scan_time_of_day]
- Optional. One of "morning", "afternoon", "evening", "night". For all schedules, represents the 6-hour PST windows the scan will begin in. The windows are (14:00-20:00 UTC), (20:00-02:00 UTC), (02:00-08:00 UTC), (08:00-14:00 UTC) respectively.
Response Description
If successful, returns the ID of the new site, along with a summary of associated information.
Note: modifying the site name can change the returned ID to be used in subsequent requests.
DELETE A SITE
Request
DELETE /api/v1/sites/:site_id
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites/:site_id -X DELETE -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Success Response
HTTP Response Code: 200
Sample Failure Response
HTTP Response Codes: 403, 404
Unrecoverably destroys a website and all associated scans. You must have full API access (not read-only) to perform this operation.
Parameters
:site_id
- Required. This is the ID
of your site, as returned by GET /api/v1/sites
.
Response Description
If successful, destroys a website and all associated scans.
START A SCAN
Request
POST /api/v1/sites/:site_id/scans
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites/:site_id/scans -X POST -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Success Response
HTTP Response Code: 201(created)
{ "scan": { "end_time": null, "id": "se1353976376418547000", "scan_type": "full", "start_time": null, "status": "unknown" } }
Sample Failure Response
HTTP Response Codes: 409(conflict), 412(precondition failed)
{ "errors": [ "Scans cannot be run on <strong>Example.org</strong> because you must verify ownership first." ] }
Begins a scan for a site. You must have full API access (not read-only) to perform this operation. The new scan is queued to begin shortly after the request returns successfully.
Parameters
:site_id
- Required. This is the ID
of your site, as returned by GET /api/v1/sites
.
Response Description
If successful, returns the ID of the new scan. If the site is not eligible to be scanned, either due an already running scan or a site that fails a precondition like verification, an error object is returned specifying the details.
STOP A SCAN
Request
PUT /api/v1/sites/:site_id/scans/:scan_id/cancel
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites/:site_id/scans/:scan_id/cancel -X PUT -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Success Response
HTTP Response Code: 200
{ "scan": { "end_time": "2012-11-28T02:38:02Z", "id": "se1353976376418547000", "scan_type": "full", "start_time": "2012-11-28T02:28:02Z", "status": "cancelled" } }
Sample Failure Response
HTTP Response Code: 500
{ "errors": [ "Scan could not be cancelled." ] "scan": { "end_time": "2012-11-28T02:38:02Z", "id": "se1353976376418547000", "scan_type": "full", "start_time": "2012-11-28T02:28:02Z", "status": "done" } }
Cancels a scan. You must have full API access (not read-only) to perform this operation. If the scan is already cancelled or done, will do nothing.
Parameters
:site_id
- Required. This is the ID
of your site, as returned by GET /api/v1/sites
.
:scan_id
- Required. This is the ID
of your scan, as returned by GET /api/v1/sites/:site_id/scans
.
Response Description
Returns the current status of the scan. An error object will be present in the case that the scanner could not immediately end the scan.
FINISH A SCAN EARLY
Request
PUT /api/v1/sites/:site_id/scans/:scan_id/finish_early
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites/:site_id/scans/:scan_id/finish_early -X PUT -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Success Response
HTTP Response Code: 202
{ "text": "Scan is queued to end early.", "scan": { "id": "se145489778629771000", "start_time": "2012-11-28T02:16:31Z", "scanner_ip_address": "54.242.161.118", "end_time": null, "scan_type": "full", "status": "scanning" } }
Finishes a scan early, adding a vulnerability that states it was not a complete scan, but providing results up to that point. This is not an immediate operation. You must have full API access (not read-only) to perform this operation. If the scan is already cancelled or done, will do nothing.
Parameters
:site_id
- Required. This is the ID
of your site, as returned by GET /api/v1/sites
.
:scan_id
- Required. This is the ID
of your scan, as returned by GET /api/v1/sites/:site_id/scans
.
Response Description
Returns the current status of the scan, and a message stating the scan is queued to be ended early.
LIST ALL SCANS FOR A SITE
Request
GET /api/v1/sites/:site_id/scans
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites/:site_id/scans?status=done -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Response
{ "total_pages":3, "page_number":1, "next_page":"https://www.tinfoilsecurity.com/api/v1/sites/example/scans?page=2", "scans":[ { "scan":{ "id":"se1352947099875001000", "start_time":"2012-11-15T02:38:30Z", "end_time":null, "scan_type":"full", "status":"scanning", "scanner_ip_address":"54.242.161.118" } }, { "scan":{ "id":"se1352946907718082000", "start_time":"2012-11-15T02:35:18Z", "end_time":null, "scan_type":"full", "status":"cancelled", "scanner_ip_address":"23.23.17.84" } }, { "scan":{ "id":"se1352759585821550000", "start_time":"2012-11-12T22:33:15Z", "end_time":"2012-11-12T23:10:10Z", "scan_type":"rudimentary", "status":"done", "scanner_ip_address":"23.23.17.84" } }, "..." ] }
Returns a list of all of the scans run on a particular site, given by :site_id
in the URL.
Parameters
:site_id
- Required. This is the ID
of your site, as returned by GET /api/v1/sites
.
status
- Optional. Use this to filter your scans by status. Allowed values are running, done, cancelled, and upcoming.
per_page
- Optional (Default is 20). Use this to specify how many records are returned on each page.
page
- Optional (Default is 1). Use this to specify which page of records to view.
Response Description
scan_type
- one of the following: full, rudimentary, rescan, or unknown.
status
- one of the following: scanning, done, upcoming, cancelled, or unknown.
total_pages
and page_number
let you know where you are in the list of scans, and next_page
provides you with a link to the next page of scans. If you are on the last page, the next_page
attribute will not be present.
GET REPORT FOR A SCAN
Request
GET /api/v1/sites/:site_id/scans/:scan_id/report
Example
$ curl https://www.tinfoilsecurity.com/api/v1/sites/:site_id/scans/:scan_id/report -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Response
{ "report":{ "total_pages":5, "page_number":1, "next_page":"https://www.tinfoilsecurity.com/api/v1/sites/example/scans/se1352759585821550000/report?page=2", "classification":"very_unsafe", "site":{ "name":"Example Site", "url":"http://www.example.org" }, "scan":{ "start_time":"2012-11-12T22:33:15Z", "end_time":"2012-11-12T23:10:10Z" }, "issues":[ { "issue":{ "id":"53f5226abd0e019ed111000a", "signature":"9cc17ebe9e8d58f2049b9719678cd2e2d972ce7aa497b2c6437911328aef69a3", "url":"http://www.example.org/search.aspx", "type":"Cross-Site Scripting (XSS)", "severity":"High", "method":"GET", "element":{ "type":"form", "name":"txtSearch" }, "attack":{ "injected":"<tinfoil_xss_9d18d1d12725466697a759028742a5502a3aa78694bfe1bd89129a22ad68c0a8/>", "request_headers":[ { "key":"Accept", "value":"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" }, "..." ], "response_headers":[ { "key":"Date", "value":"Tue, 13 Nov 2012 00:29:44 GMT" }, "..." ], "params":[ { "key":"txtSearch", "value":"<tinfoil_xss_c6c8f8e873d71f7d84b4f358540e18a0a80b89ee4d3fe69af9497bf380bd20db/>" } ] } } } }, "..." ] } }
Returns the full report for a completed scan, given a :site_id
and a :scan_id
.
Parameters
:site_id
- Required. This is the ID
of your site, as returned by GET /api/v1/sites
.
:scan_id
- Required. This is the ID
of your scan, as returned by GET /api/v1/sites/:site_id/scans
.
per_page
- Optional (Default is 10). Use this to specify how many records are returned on each page.
page
- Optional (Default is 1). Use this to specify which page of records to view.
Response Description
Reports can get very large, as they include the request and response headers for each vulnerability we found. Therefore, the report is paginated. total_pages
and page_number
let you know where you are in the list of issues, and next_page
provides you with a link to the next page of issues. If you are on the last page, the next_page
attribute will not be present.
Get information about the current API Key
Request
GET /api/v1/api_keys/info
Example
$ curl https://www.tinfoilsecurity.com/api/v1/api_keys/info -H 'Authorization:Token token=YOUR_API_SECRET_KEY, access_key=YOUR_API_ACCESS_KEY'
Sample Response
{ "api_key":{ "name":"API Key", "active":true, "access_key":"YOUR_API_ACCESS_KEY", "read_only":false } }
Returns information about the current API key being used.
Response Description
read_only
will be true for read_only
keys, and false for full_access
keys.