Skip to content

REST API

Jump to bottom
Elías Grande edited this page Mar 25, 2017 · 51 revisions

When you start the Dagda server, it gives you full access to Dagda via REST API. Every aspect of Dagda can be controlled via this API. The Dagda CLI uses the REST API to access Dagda.

See the start sub-command for knowning how to start Dagda server.

At the moment, the REST API has the next services shown below:

Version Prefix

All API routes are prefixed with /v1/.

Backwards compatibility: At the current version, Dagda does not yet promise backwards compatibility even with the v1 prefix.

HTTP Status Codes

The following HTTP status codes are used throughout the API.

  • 200 - Success with data.
  • 202 - Success, the request has been accepted for processing, but the processing has not been completed.
  • 400 - Invalid request, missing or invalid data.
  • 404 - Invalid path or requested resource not found.
  • 500 - Internal server error. An internal error has occurred, try again later. If the error persists, report a bug.
  • 503 - Some Dagda service is down. Review Dagda logs.

REST API Services

check service

check/images/<path:image_name>

DESCRIPTION Performs a static analysis of known vulnerabilities over a
a docker image.
METHOD POST
URL check/images/<path:image_name>
PARAMETERS None
RETURNS HTTP/1.1 202 Accepted
{
    "id": "58667994ed253915723c50e7",
    "msg": "Accepted the analysis of <IMAGE_NAME>"
}

check/containers/<string:container_id>

DESCRIPTION Performs a static analysis of known vulnerabilities over a
running docker container.
METHOD POST
URL check/containers/<string:container_id>
PARAMETERS None
RETURNS HTTP/1.1 202 Accepted
{
    "id": "58667994ed253915723c50e7",
    "msg": "Accepted the analysis of <IMAGE_NAME> with id: <CONTAINER_ID>"
}

docker service

docker/images

DESCRIPTION Gets all docker images.
METHOD GET
URL docker/images
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[{
	"created": "2017-01-08 10:59:37",
	"id": "f846515186f0",
	"size": "96.2MB",
	"tags": ["dagda_dagda:latest"]
}, {
	"created": "2016-12-27 21:39:19",
	"id": "0eb0091592b3",
	"size": "78.5MB",
	"tags": ["python:3.4.5-alpine"]
}, {
	"created": "2016-12-22 23:25:19",
	"id": "285353e9835d",
	"size": "330.0MB",
	"tags": ["sysdig/falco:latest"]
}, {
	"created": "2016-11-30 22:08:11",
	"id": "86e302671af4",
	"size": "383.3MB",
	"tags": ["mongo:latest"]
}]

docker/containers

DESCRIPTION Gets all running docker containers.
METHOD GET
URL docker/containers
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[{
	"created": "2017-01-14 13:32:51",
	"id": "1f24adfd7949",
	"image": "mongo",
	"name": "compassionate_bohr",
	"status": "running"
}, {
	"created": "2017-01-14 13:31:37",
	"id": "9b2c4fe055bc",
	"image": "sysdig/falco",
	"name": "adoring_shaw",
	"status": "running"
}]

history service

history

DESCRIPTION Gets the full analysis history.
METHOD GET
URL history
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[{
	"anomalies": 0,
	"image_name": "jboss/wildfly",
	"libs_vulns": 9,
	"os_vulns": 42,
	"reportid": "58790707ed253944951ec5ba",
	"start_date": "2017-01-13 17:01:09.072675",
	"status": "Completed"
}, {
	"anomalies": 0,
	"image_name": "mongo",
	"libs_vulns": 0,
	"os_vulns": 0,
	"reportid": "58790611ed25393b1b299558",
	"start_date": "2017-01-13 16:53:37.001113",
	"status": "Analyzing"
}, {
	"anomalies": 2,
	"image_name": "jboss/wildfly",
	"libs_vulns": 0,
	"os_vulns": 0,
	"reportid": "586f7a48ed25397777c67dea",
	"start_date": "2017-01-06 11:06:48.541235",
	"status": "Monitoring"
}]

history/<path:image_name>

DESCRIPTION Gets the full analysis history for the requested docker image
name, included all static analysis and all runtime monitoring.
METHOD GET
URL history/<path:image_name>
PARAMETERS id: optional filter for getting only the report with this id
RETURNS HTTP/1.1 200 OK
[
   {
      "id": "586f7631ed25396a829baaf4",
      "image_name": "jboss/wildfly",
      "timestamp": "2017-01-06 10:49:21.212508",
      "status": "Completed",
      "runtime_analysis": {
         "container_id": "69dbf26ab368",
         "start_timestamp": "2017-01-06 10:49:21.212508",
         "stop_timestamp": "2017-01-06 10:50:16.343847",
         "anomalous_activities_detected": {
            "anomalous_counts_by_severity": {
               "Warning": 2
            },
            "anomalous_activities_details": [{
               "output": "10:49:47.492517329: Warning Unexpected setuid call by non-sudo, non-root program (user=<NA> command=ping 8.8.8.8 uid=<NA>) container=thirsty_spence (id=69dbf26ab368)",
               "priority": "Warning",
               "rule": "Non sudo setuid",
               "time": "2017-01-06 10:49:47.492516"
            }, {
               "output": "10:49:53.181654702: Warning Unexpected setuid call by non-sudo, non-root program (user=<NA> command=ping 8.8.4.4 uid=<NA>) container=thirsty_spence (id=69dbf26ab368)",
               "priority": "Warning",
               "rule": "Non sudo setuid",
               "time": "2017-01-06 10:49:53.181653"
            }]
         }
      }
   },
   {
      "id": "58667994ed253915723c50e7",
      "image_name": "jboss/wildfly",
      "status": "Completed",
      "timestamp": "2016-12-14 13:17:12.802486",
      "static_analysis": {
          "os_packages": {
             "total_os_packages": 182,
             "vuln_os_packages": 41,
             "ok_os_packages": 141,
             "os_packages_details": [
                {
                   "product": "sed",
                   "version": "4.2.2",
                   "is_vulnerable": false,
                   "vulnerabilities": []
                },
                {
                   "product": "grep",
                   "version": "2.20",
                   "is_vulnerable": true,
                   "vulnerabilities": [
                      "CVE-2015-1345"
                   ]
                },
                {
                   "product": "lua",
                   "version": "5.1.4",
                   "is_vulnerable": true,
                   "vulnerabilities": [
                      "CVE-2014-5461",
                      "BID-34237"
                   ]
                },
                [...]
                , {
                   "product": "sqlite",
                   "version": "3.7.17",
                   "is_vulnerable": false,
                   "vulnerabilities": []
                }
             ]
          },
          "prog_lang_dependencies": {
             "vuln_dependencies": 9,
             "dependencies_details": {
                "java": [
                   {
                      "product": "xalan-java",
                      "version": "2.5.2",
                      "vulnerabilities": [
                         "CVE-2014-0107",
                         "BID-30591",
                         "BID-32862",
                         "BID-66397"
                      ]
                   },
                   {
                      "product": "jboss_wildfly_application_server",
                      "version": "-",
                      "vulnerabilities": [
                         "CVE-2014-0018"
                      ]
                   },
                   [...]
                   , {
                      "product": "jboss_weld",
                      "version": "3.0.0",
                      "vulnerabilities": [
                         "CVE-2014-8122",
                         "BID-74252"
                      ]
                   }
                ],
                "js": [],
                "nodejs": [],
                "php": [],
                "python": [
                   {
                      "product": "lxml",
                      "version": "1.0.1",
                      "vulnerabilities": [
                         "CVE-2014-3146"
                      ]
                   }
                ],
                "ruby": []
             }
          }
       }
   }
]

monitor service

monitor/containers/<string:container_id>/start

DESCRIPTION Starts to monitoring a running docker container for detecting
anomalous activities.
METHOD POST
URL monitor/containers/<string:container_id>/start
PARAMETERS None
RETURNS HTTP/1.1 202 Accepted
{
	"id": "586f7631ed25396a829baaf4", 
    "image_name": "jboss/wildfly", 
    "msg": "Monitoring of docker container with id <69dbf26ab368> started"
}

monitor/containers/<string:container_id>/stop

DESCRIPTION Stops the monitoring over a running docker container.
METHOD POST
URL monitor/containers/<string:container_id>/stop
PARAMETERS None
RETURNS HTTP/1.1 200 OK
{
   "id": "586f7631ed25396a829baaf4",
   "image_name": "jboss/wildfly",
   "timestamp": "2017-01-06 10:49:21.212508",
   "status": "Completed",
   "runtime_analysis": {
      "container_id": "69dbf26ab368",
      "start_timestamp": "2017-01-06 10:49:21.212508",
      "stop_timestamp": "2017-01-06 10:50:16.343847",
      "anomalous_activities_detected": {
         "anomalous_counts_by_severity": {
            "Warning": 2
         },
         "anomalous_activities_details": [{
            "output": "10:49:47.492517329: Warning Unexpected setuid call by non-sudo, non-root program (user=<NA> command=ping 8.8.8.8 uid=<NA>) container=thirsty_spence (id=69dbf26ab368)",
            "priority": "Warning",
            "rule": "Non sudo setuid",
            "time": "2017-01-06 10:49:47.492516"
         }, {
            "output": "10:49:53.181654702: Warning Unexpected setuid call by non-sudo, non-root program (user=<NA> command=ping 8.8.4.4 uid=<NA>) container=thirsty_spence (id=69dbf26ab368)",
            "priority": "Warning",
            "rule": "Non sudo setuid",
            "time": "2017-01-06 10:49:53.181653"
         }]
      }
   }
}

vuln service

vuln/init

DESCRIPTION Initializes or updates the vulnerabilities database.
METHOD POST
URL vuln/init
PARAMETERS None
RETURNS HTTP/1.1 202 Accepted
{
    "msg": "Accepted the init db request"
}

vuln/init-status

DESCRIPTION Returns the initialization status of the vulnerabilities database.
METHOD GET
URL vuln/init-status
PARAMETERS None
RETURNS HTTP/1.1 200 OK
{
    "status": "Updated", 
    "timestamp": "2016-12-31 12:32:14.381080"
}

vuln/bid/<int:bid_id>

DESCRIPTION Gets the vulnerable products by BID.
METHOD GET
URL vuln/bid/<int:bid_id>
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[
    { 
    	"product" : "<PRODUCT_NAME>", 
        "version" : "<PRODUCT_VERSION>"
    },
    { 
    	"product" : "<PRODUCT_NAME>", 
        "version" : "<PRODUCT_VERSION>"
    }
]

vuln/cve/<string:cve_id>

DESCRIPTION Gets the vulnerable products by CVE.
METHOD GET
URL vuln/cve/<string:cve_id>
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[
    { 
    	"vendor" : "<PRODUCT_VENDOR>",
    	"product": "<PRODUCT_NAME>", 
        "version": "<PRODUCT_VERSION>",
        "year" : "<CVE_YEAR>"
    },
    { 
    	"vendor" : "<PRODUCT_VENDOR>",
    	"product": "<PRODUCT_NAME>", 
        "version": "<PRODUCT_VERSION>",
        "year" : "<CVE_YEAR>"
    }
]

vuln/cve/<string:cve_id>/details

TO-DO

vuln/exploit/<int:exploit_id>

DESCRIPTION Gets the vulnerable products by ExploitDB Id.
METHOD GET
URL vuln/exploit/<int:exploit_id>
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[
    { 
    	"product" : "<PRODUCT_NAME>", 
        "version" : "<PRODUCT_VERSION>"
    },
    { 
    	"product" : "<PRODUCT_NAME>", 
        "version" : "<PRODUCT_VERSION>"
    }
]

vuln/products/<string:product>(/<string:version>)

DESCRIPTION Gets the CVEs, BIDs and Exploit_DB Ids by product and version.
METHOD GET
URL vuln/products/<string:product>(/<string:version>)
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[
    "CVE-<CVE_ID_1>",
    "CVE-<CVE_ID_2>", 
    "CVE-<CVE_ID_3>", 
    "BID-<BID_ID_1>", 
    "BID-<BID_ID_2>", 
    "EXPLOIT_DB_ID-<EXPLOIT_DB_ID_1>"
]
Clone this wiki locally