Skip to content

Relwarc Documentation

Relwarc is a client-side JavaScript analyzer for discovering server HTTP endpoints. It analyzes the JavaScript code of web pages to determine what requests can be sent from it to the server.

Relwarc provides an API allowing to request the analysis of web pages or individual JS code samples. API server is located at https://relwarc.solidpoint.net/.

Relwarc is a component of a black-box web security scanner SolidPoint.

API documentation

The base URL for all API requests is https://relwarc.solidpoint.net/api/.

API token

API endpoints require a valid API token. For all HTTP API endpoints the token should be sent in X-API-Token HTTP header.

Like this:

curl -H 'X-API-Token: d89..24ef' https://relwarc.solidpoint.net/api/job/1

WebSocket endpoint for watching analysis progress has a different method of supplying the token (see below).

An API token can be obtained in the user interface here: https://relwarc.solidpoint.net/user/token.

Responses

All HTTP API endpoints will return the response with JSON body. In case of an error, the JSON object in the response body will contain the field "error" describing the error. For example: 

{
  "error": "failed to find job: Unknown job: 220"
}

For response format of successful responses, see the description of individual endpoints.

Requesting the analysis

There are several ways to create analysis tasks. For all of them, in case of success, an analysis job is enqueued and the response with status 200 is returned, with a body containing the job id for this analysis job. The response body has the following format:

{
  "job_id": 5
}

This job id can be used to track the progress of the analysis process and to get the result.

Analyzing a page given its URL

POST https://relwarc.solidpoint.net/api/analyze-url

Request body should contain the plain URL of the page to be analyzed. For example:

curl -H "X-API-Token: $RELWARC_API_TOKEN" \
  -H 'Content-Type: text/plain' \
  --data-binary 'http://juice-shop.stands.solidpoint.net/' \
  https://relwarc.solidpoint.net/api/analyze-url

Analyzing a source code sample

POST https://relwarc.solidpoint.net/api/analyze-code

Request body should contain the plain JavaScript source code to be analyzed. For example:

curl -H "X-API-Token: $RELWARC_API_TOKEN" \
  -H 'Content-Type: text/javascript' \
  --data-binary 'var d = "data"; fetch("/get"+d);' \
  https://relwarc.solidpoint.net/api/analyze-code

Or, to analyze the JS sample contained in file ./sample.js:

curl -H "X-API-Token: $RELWARC_API_TOKEN" \
  -H 'Content-Type: text/javascript' \
  --data-binary '@./sample.js' \
  https://relwarc.solidpoint.net/api/analyze-code

Analyzing a page packed as a tar archive

POST https://relwarc.solidpoint.net/api/analyze-tar

Request body should contain the tar archive with the page that should be analyzed. For example:

curl -H "X-API-Token: $RELWARC_API_TOKEN" \
  -H 'Content-Type: application/x-tar' \
  --data-binary '@./pages/page.tar' \
  https://relwarc.solidpoint.net/api/analyze-tar

The archive format it described here.

Getting the job status and the result

GET https://relwarc.solidpoint.net/api/job/<job_id>

For example:

curl -H "X-API-Token: $RELWARC_API_TOKEN" \
  https://relwarc.solidpoint.net/api/job/3

The successful reponse will have the following format: 

{
  "job_id": 10,
  "status": "<job status>",
  "logs": [
    "log record 1",
    "log record 2",
    ...
  ],
  "result": [
    { ... },
    { ... },
    ...
  ]
}

The "status" field may have the following values:

  • "new"
  • "waiting-for-worker"
  • "processing"
  • "done"
  • "error"

New statuses may be added in future.

The field "result" may be absent, it should be expected only for jobs with status "done". The objects in the "result" array describe the discovered requests. The format of each object is very similar to how the requests are described in the HAR format.

Log records are strings.

Watching the job status using WebSockets

The API server provides a WebSocket endpoint allowing to track analysis progress and get notified about its completion (or failure).

The endpoint address is:

wss://relwarc.solidpoint.net/api/job/watch

After connecting to it, a single JSON object should be sent by the client:

{
  "token": "<Relwarc API token>",
  "job_id": 25
}

The server will then send notifications about the analysis progress to that connection.

Notifications are JSON objects, each notification will have the field "type". There are currently 3 types of notifications:

1. Log messages

{
  "type": "log",
  "message": "Log message here"
}

Log messages are strings, they are the same as those returned by the GET /api/job/<job_id> endpoint.

2. Result message

{
  "type":"result",
  "result":[
    { ... },
    { ... },
    ...
  ]
}

3. Failure message

{
  "type":"error",
  "message":"Error"
}

There are usually multiple "log" messages followed by a single final message, which is either a "result" message or an "error" message. "result" (or "error") is guaranteed to be the last message, after receiving it the client should disconnect. Objects in the "result" array are the same as those in the response to the GET /api/job/<job_id> endpoint.

Contacts

Contact email: relwarc@solidpoint.net