Distributed Cuckoo¶

Report Formats¶

The reporting formats denote which reports you’d like to retrieve later on. Note that all task-related data will be removed from the Cuckoo nodes once the related reports have been fetched so that the machines are not running out of disk space. This does, however, force you to specify all the report formats that you’re interested in, because otherwise that information will be lost.

Reporting formats include, but are not limited to and may also include your own reporting formats, report.json, report.html, etc.

Samples Directory¶

The samples directory denotes the directory where the submitted samples will be stored temporarily, until the associated task has been deleted.

Reports Directory¶

Much like the Samples Directory the Reports Directory defines the directory where reports will be stored until they’re fetched and deleted from the Distributed REST API.

GET /api/node¶

Returns all enabled nodes. For each node the information includes the associated name, its API URL, and machines:

$ curl http://localhost:9003/api/node
{
    "success": true,
    "nodes": {
        "localhost": {
            "machines": [
                {
                    "name": "cuckoo1",
                    "platform": "windows",
                    "tags": []
                }
            ],
            "name": "localhost",
            "url": "http://localhost:8090/"
        }
    }
}

POST /api/node¶

Register a new Cuckoo node by providing the name and the URL:

$ curl http://localhost:9003/api/node -F name=localhost \
    -F url=http://localhost:8090/
{
    "success": true
}

GET /api/node/<name>¶

Get basic information about a particular Cuckoo node:

$ curl http://localhost:9003/api/node/localhost
{
    "success": true,
    "nodes": [
        {
            "name": "localhost",
            "url": "http://localhost:8090/"
            "machines": [
                {
                    "name": "cuckoo1",
                    "platform": "windows",
                    "tags": []
                }
            ]
        }
    ]
}

PUT /api/node/<name>¶

Update basic information of a Cuckoo node:

$ curl -XPUT http://localhost:9003/api/node/localhost -F name=newhost \
    -F url=http://1.2.3.4:8090/
{
    "success": true
}

POST /api/node/<name>/refresh¶

Refreshes metadata associated by a Cuckoo node, in particular, its machines:

$ curl -XPOST http://localhost:9003/api/node/localhost/refresh
{
    "success": true,
    "machines": [
        {
            "name": "cuckoo1",
            "platform": "windows",
            "tags": []
        },
        {
            "name": "cuckoo2",
            "platform": "windows",
            "tags": []
        }
    ]
}

DELETE /api/node/<name>¶

Disable a Cuckoo node, therefore not having it process any new tasks, but keeping its history in the Distributed Cuckoo database:

$ curl -XDELETE http://localhost:9003/api/node/localhost
{
    "success": true
}

GET /api/task¶

Get a list of all tasks in the database. In order to limit the amount of results, there’s an offset, limit, finished, and owner field available:

$ curl http://localhost:9003/api/task?limit=1
{
    "success": true,
    "tasks": {
        "1": {
            "clock": null,
            "custom": null,
            "owner": "",
            "enforce_timeout": null,
            "machine": null,
            "memory": null,
            "options": null,
            "package": null,
            "path": "/tmp/dist-samples/tmphal8mS",
            "platform": "windows",
            "priority": 1,
            "tags": null,
            "task_id": 1,
            "timeout": null
        }
    }
}

POST /api/task¶

Submit a new file or URL to be analyzed:

$ curl http://localhost:9003/api/task -F file=@sample.exe
{
    "success": true,
    "task_id": 2
}

GET /api/task/<id>¶

Get basic information about a particular task:

$ curl http://localhost:9003/api/task/2
{
    "success": true,
    "tasks": {
        "2": {
            "id": 2,
            "clock": null,
            "custom": null,
            "owner": "",
            "enforce_timeout": null,
            "machine": null,
            "memory": null,
            "options": null,
            "package": null,
            "path": "/tmp/tmpPwUeXm",
            "platform": "windows",
            "priority": 1,
            "tags": null,
            "timeout": null,
            "task_id": 1,
            "node_id": 2,
            "finished": false
        }
    }
}

DELETE /api/task/<id>¶

Delete all associated data of a task, namely the binary, the PCAP, and the reports:

$ curl -XDELETE http://localhost:9003/api/task/2
{
    "success": true
}

GET /api/report/<id>/<format>¶

Fetch a report for the given task in the specified format:

# Defaults to the JSON report.
$ curl http://localhost:9003/api/report/2
...

GET /api/pcap/<id>¶

Fetches the PCAP for the given task:

$ curl http://localhost:9003/api/pcap/2
...

Configuration settings¶

Our setup will require a couple of updates with regards to the configuration files.

Setup Cuckoo¶

On each machine you will have to run the Cuckoo Daemon, the Cuckoo API, and one or more Cuckoo Process instances. For more information on setting that up, please refer to Starting Cuckoo.

Setup Distributed Cuckoo¶

On the Distributed Cuckoo machine you’ll have to setup the Distributed Cuckoo REST API and the Distributed Cuckoo Worker.

As stated earlier, Distributed Cuckoo REST API may be started by running cuckoo distributed server or by deploying it properly with uWSGI and nginx.

The Distributed Cuckoo Worker may be started by running supervisorctl start distributed in the CWD (make sure to start supervisord first as per Cuckoo in the background). This will automatically start the Worker with the correct configuration and arguments, etc.

Register Cuckoo nodes¶

As outlined in Quick usage the Cuckoo nodes have to be registered with the Distributed Cuckoo REST API:

$ curl http://localhost:9003/api/node -F name=cuckoo0 -F url=http://localhost:8090/
$ curl http://localhost:9003/api/node -F name=cuckoo1 -F url=http://1.2.3.4:8090/

Having registered the Cuckoo nodes all that’s left to do now is to submit tasks and fetch reports once finished. Documentation on these commands can be found in the Quick usage section. In case your Cuckoo node is not on localhost, replace localhost with the IP address of the node where the Cuckoo REST API is running.

If you want to experiment with load balancing between the nodes you may want to try using a lower value for the threshold parameter in the $CWD/distributed/settings.py file as the default value is 500 (meaning tasks are assigned to Cuckoo nodes in batches of 500).