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": {
                           "cveid": "CVE-2015-1345",
                           "cvss_access_complexity": "Low",
                           "cvss_access_vector": "Local access",
                           "cvss_authentication": "None required",
                           "cvss_availability_impact": "Partial",
                           "cvss_base": 2.1,
                           "cvss_confidentiality_impact": "None",
                           "cvss_exploit": 3.9,
                           "cvss_impact": 2.9,
                           "cvss_integrity_impact": "None",
                           "cvss_vector": [
                              "AV:L",
                              "AC:L",
                              "Au:N",
                              "C:N",
                              "I:N",
                              "A:P"
                           ],
                           "cweid": "CWE-119",
                           "mod_date": "23-12-2016",
                           "pub_date": "12-02-2015",
                           "summary": "The bmexec_trans function in kwset.c in grep 2.19 through 2.21 allows local users to cause a denial of service (out-of-bounds heap read and crash) via crafted input when using the -F option."
                        }
                     }
                  ]
               },
               {
                  "is_vulnerable": true,
                  "product": "lua",
                  "version": "5.1.4",
                  "vulnerabilities": [
                     {
                        "CVE-2014-5461": {
                           "cveid": "CVE-2014-5461",
                           "cvss_access_complexity": "Low",
                           "cvss_access_vector": "Network",
                           "cvss_authentication": "None required",
                           "cvss_availability_impact": "Partial",
                           "cvss_base": 5.0,
                           "cvss_confidentiality_impact": "None",
                           "cvss_exploit": 10.0,
                           "cvss_impact": 2.9,
                           "cvss_integrity_impact": "None",
                           "cvss_vector": [
                              "AV:N",
                              "AC:L",
                              "Au:N",
                              "C:N",
                              "I:N",
                              "A:P"
                           ],
                           "cweid": "CWE-119",
                           "mod_date": "06-01-2017",
                           "pub_date": "04-09-2014",
                           "summary": "Buffer overflow in the vararg functions in ldo.c in Lua 5.1 through 5.2.x before 5.2.3 allows context-dependent attackers to cause a denial of service (crash) via a small number of arguments to a function with a large number of fixed arguments."
                        }
                     },
                     {
                        "BID-34237": ""
                     }
                  ]
               },
               [...]
               , {
                  "is_vulnerable": false,
                  "product": "sqlite",
                  "version": "3.7.17",
                  "vulnerabilities": []
               }
            ]
         },
         "prog_lang_dependencies": {
            "vuln_dependencies": 9,
             "dependencies_details": {
                "java": [
                   {
                      "product": "xalan-java",
                      "version": "2.5.2",
                      "vulnerabilities": [
                         {
                            "CVE-2014-0107": {
                               "cveid": "CVE-2014-0107",
                               "cvss_access_complexity": "Low",
                               "cvss_access_vector": "Network",
                               "cvss_authentication": "None required",
                               "cvss_availability_impact": "Partial",
                               "cvss_base": 7.5,
                               "cvss_confidentiality_impact": "Partial",
                               "cvss_exploit": 10.0,
                               "cvss_impact": 6.4,
                               "cvss_integrity_impact": "Partial",
                               "cvss_vector": [
                                  "AV:N",
                                  "AC:L",
                                  "Au:N",
                                  "C:P",
                                  "I:P",
                                  "A:P"
                               ],
                               "cweid": "CWE-264",
                               "mod_date": "06-01-2017",
                               "pub_date": "15-04-2014",
                               "summary": "The TransformerFactory in Apache Xalan-Java before 2.7.2 does not properly restrict access to certain properties when FEATURE_SECURE_PROCESSING is enabled, which allows remote attackers to bypass expected restrictions and load arbitrary classes or access external resources via a crafted (1) xalan:content-header, (2) xalan:entities, (3) xslt:content-header, or (4) xslt:entities property, or a Java property that is bound to the XSLT 1.0 system-property function."
                               }
                            },
                            {
                               "BID-30591": ""
                            },
                            {
                               "BID-32862": ""
                            },
                            {
                               "BID-66397": ""
                            }
                         ]
                      },
                      [...] 
                   ],
                   "js": [],
                   "nodejs": [],
                   "php": [],
                   "python": [
                      {
                         "product": "lxml",
                         "version": "1.0.1",
                         "vulnerabilities": [
                            {
                               "CVE-2014-3146": {
                                  "cveid": "CVE-2014-3146",
                                  "cvss_access_complexity": "Medium",
                                  "cvss_access_vector": "Network",
                                  "cvss_authentication": "None required",
                                  "cvss_availability_impact": "None",
                                  "cvss_base": 4.3,
                                  "cvss_confidentiality_impact": "None",
                                  "cvss_exploit": 8.6,
                                  "cvss_impact": 2.9,
                                  "cvss_integrity_impact": "Partial",
                                  "cvss_vector": [
                                     "AV:N",
                                     "AC:M",
                                     "Au:N",
                                     "C:N",
                                     "I:P",
                                     "A:N"
                                  ],
                                  "cweid": "CWE-0",
                                  "mod_date": "14-04-2015",
                                  "pub_date": "14-05-2014",
                                  "summary": "Incomplete blacklist vulnerability in the lxml.html.clean module in lxml before 3.3.5 allows remote attackers to conduct cross-site scripting (XSS) attacks via control characters in the link scheme to the clean_html function."
                               }
                            }
                         ]
                     }
                 ],
                 "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

DESCRIPTION Gets the CVE vulnerability details.
METHOD GET
URL vuln/cve/<string:cve_id>/details
PARAMETERS None
RETURNS HTTP/1.1 200 OK
[
   {
      "cveid": "CVE-2009-2890",
      "cvss_access_complexity": "Medium",
      "cvss_access_vector": "Network",
      "cvss_authentication": "None required",
      "cvss_availability_impact": "None",
      "cvss_base": 4.3,
      "cvss_confidentiality_impact": "None",
      "cvss_exploit": 8.6,
      "cvss_impact": 2.9,
      "cvss_integrity_impact": "Partial",
      "cvss_vector": [
         "AV:N",
         "AC:M",
         "Au:N",
         "C:N",
         "I:P",
         "A:N"
      ],
      "cweid": "CWE-79",
      "mod_date": "20-08-2009",
      "pub_date": "20-08-2009",
      "summary": "Cross-site scripting (XSS) vulnerability in results.php in PHP Scripts Now Riddles allows remote attackers to inject arbitrary web script or HTML via the searchquery parameter."
   }
]

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