API

DeepTracy API is divided in two parts: a control API and a query API.

Control API

The control API is provided by DeepTracy Server service and allows the user to manage the scanning tasks with a minimal REST API.

POST /analysis/

Create and start a new analysis for the given repository & commit.

Requires a JSON object with the following parameters:
  • repository: The repository.

  • commit: The commit.

  • webhook (optional): Webhook to notify to when the analysis finish.

Example:

{"repository": "https://github.com/nilp0inter/gitsectest",
 "commit": "fdd09edd73f3fe87ea4265eeddb95935c7d25a51",
 "webhook": "http://myapp.com/analysis-finished"}

Returns a JSON object containing the id of the created analysis.

{"id": "b6e98743-7830-4aef-adf6-6a0b022f778a"}
PUT /analysis/(analysis_id)/extraction/started

Signal from buildbot that the extraction phase for an analysis has started.

Note

Internal API

PUT /analysis/(analysis_id)/extraction/succeeded

Dependency extraction phase succeeded.

Must contain a JSON object with the number of tasks spawned in the server (requests made to /dependencies and /vulnerabilities endpoints.

Example result:

{'task_count': <int>}

Note

Internal API

PUT /analysis/(analysis_id)/extraction/failed

Dependency extraction phase failed.

Note

Internal API

POST /analysis/(analysis_id)/(execution_id)/dependencies

Installation data from buildbot.

Requires a JSON list of objects with the following keys:
  • installer: The system used to install the dependency.

  • spec: The full specification used by the user to request the

    package.

  • source: Entity providing the artifact.

  • name: The real package name.

  • version: The installed version of the package.

Note

Internal API

POST /analysis/(analysis_id)/(execution_id)/vulnerabilities

Vulnerability data from buildbot.

Requires a JSON list of objects with the following keys:
  • provider: Name of the system providing the vulnerability information.

  • reference: Provider unique identifier of the vulnerability.

  • details: Extended JSON metadata.

  • installation: JSON object containing:
    • installer: The system used to install the dependency.

    • spec: The full specification used by the user to request the

      package.

    • source: Entity providing the artifact.

    • name: The real package name.

    • version: The installed version of the package.

Note

Internal API

Query API

The query API is provided by Hasura service allowing the user retrieve any report structure she wants using GraphQL language.

The complete reference manual for Hasura can be found here.

The following example illustrate how to request all the vulnerabilities for a given analysis:

GET /v1alpha1/graphql

Perform the given query and return a JSON object with the results.

Example request

POST /v1alpha1/graphql HTTP/1.1
Content-Type: application/json

  {
    "query": "{\n    analysis (where: {id: {_eq: \"904a2117-1da1-4c9c-a3d5-b03262f53d97\"}}){\n      state\n      installations {\n      \tspec\n        artifact {\n            name\n          \tversion\n            vulnerabilities {\n              provider\n              reference\n              details\n            }\n        }\n      }\n    }\n}\n",
    "variables": null
  }

Example response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Date: Fri, 24 Aug 2018 11:21:03 GMT
Server: Warp/3.2.22
Access-Control-Allow-Origin: http://localhost:8080
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET,POST,PUT,PATCH,DELETE,OPTIONS
Content-Type: application/json; charset=utf-8

  {
    "data": {
      "target": [
        {
          "repository": "https://github.com/nilp0inter/gitsectest",
          "analyses": [
            {
              "state": "SUCCESS",
              "installations": [
                {
                  "artifact": {
                    "name": "Django",
                    "version": "1.4.4",
                    "vulnerabilities": [
                      {
                        "reference": "CVE-2013-1443",
                        "details": {
                          "cve": "CVE-2013-1443",
                          "score": 5,
                          "summary": "The authentication framework (django.contrib.auth) in Django 1.4.x before 1.4.8, 1.5.x before 1.5.4, and 1.6.x before 1.6 beta 4 allows remote attackers to cause a denial of service (CPU consumption) via a long password which is then hashed."
                        },
                        "provider": "patton"
                      }
                    ],
                    "source": "pypi"
                  },
                  "spec": "django",
                  "id": "c4cc6c32-de4e-457d-a1b0-14adeeeaeec4"
                },
                {
                  "artifact": {
                    "name": "org.springframework.boot:spring-boot-starter-web",
                    "version": "1.1.5.RELEASE",
                    "vulnerabilities": [],
                    "source": "central.maven.org"
                  },
                  "spec": "org.springframework.boot:spring-boot-starter-web:jar:1.1.5.RELEASE:compile",
                  "id": "b0ea360d-60a4-4817-a4f3-978f44bd2d95"
                },
                {
                  "artifact": {
                    "name": "y18n",
                    "version": "3.2.1",
                    "vulnerabilities": [],
                    "source": "https://registry.npmjs.org/y18n/-/y18n-3.2.1.tgz"
                  },
                  "spec": "y18n@^3.2.1",
                  "id": "fce4863f-db14-4702-849d-0315d324c2e2"
                }
              ],
              "id": "4b200a05-f514-40fc-94b5-12ec5dbe5985",
              "started": "2018-08-24T12:08:02.852095"
            }
          ],
          "commit": "a5a01ca69ac99c793ec5af1bbc190f518d8fc412"
        }
      ]
    }
  }
Query Parameters
  • query – GraphQL query

  • variables – List of variables to be used within the GraphQL query.

An example request using curl.

$ curl 'http://localhost:8080/v1alpha1/graphql' \
       -H 'Content-Type: application/json' \
       --data-binary '
         {"query":"
            {
              analysis (where: {id: {_eq: \"904a2117-1da1-4c9c-a3d5-b03262f53d97\"}}){
                state
                installations {
                  spec
                  artifact {
                    name
                    version
                    vulnerabilities {
                      provider
                      reference
                      details
                    }
                  }
                }
              }
            }",
         "variables":null}'