Test/Build cuckoobuild

Cuckoobot

What?

Cuckoobot is a tool created to perform functional tests on the analysis part of Cuckoo Sandbox.

Functional testing

Cuckoobot can setup a Cuckoo Sandbox instance or use an existing Cuckoo instance if it is present in its configuration.

The functional testing uses files containing 'expected' output from an analysis, we call these the test files. Each test file is tied to a specific binary. Upon running a new functional test, all binaries will be submitted to a new or existing Cuckoo Sandbox instance.

A test file consists of a set of JSON keys containing test information and the actual tests. The current version of Cuckoobot support multiple test types, keys that define the expected DLLs loaded, network hosts contacted, files created etc.

Test files can be grouped together into categories. This can be useful if there are multiple tests which test specific functionality of Cuckoo.

Starting a test

After the submission of a binary to Cuckoo, Cuckoobot keeps track of the analysis status and downloads the results when those are available. After retrieving the results, the test which uses this binary will the performed.

The results will be searched for the expected data. For a test to pass, all expected results must be present in the retrieved results.

Test example This is an example of some tests that a test file may contain. In this case, the test is for a small Java program.

    "tests": {
        "check_expected_dll_loaded": [
            "*\\bin\\java.dll"
        ],
        "check_expected_files_written": [
            "C:\\*\\Desktop\\test.txt"
        ], 
        "check_md5": "4f78a0324f08d1c2e3baaef199ed4bd3", 
        "check_sha1": "21fdff3b0de78814c639f31869d0ca61f7f7173d", 
        "check_sha256": "31c287005379bf6273e7f2b91ae510aa55138366961e33e789caafda65ae5bb7", 
        "check_sha512": "235652516ae9f1daa2dc799d070071f38a8f39843240356f214327867fd708fa02682d841fd627f847963326a1c07449a7b56cd5a5e4b67264de38c3afcc7b27"
    }

Test result After running a test, it can pass or fail. The following is the result of running the test above.

{
    "summary": {
        "category": "filetypes",
        "cuckoo_id": 176,
        "end_result": "Passed",
        "machine_name": "w7cuckoo1",
        "percentage_passed": 100.0,
        "sample_sha1": "21fdff3b0de78814c639f31869d0ca61f7f7173d",
        "sample_sha256": "31c287005379bf6273e7f2b91ae510aa55138366961e33e789caafda65ae5bb7",
        "test_name": "test-javajar",
        "total_failed": 0,
        "total_passed": 6,
        "total_tests": 6
    },
    "test_result": {
        "check_expected_dll_loaded": {
            "*\\bin\\java.dll": "Pass"
        },
        "check_expected_files_written": {
            "C:\\*\\Desktop\\test.txt": "Pass"
        },
        "check_md5": {
            "4f78a0324f08d1c2e3baaef199ed4bd3": "Pass"
        },
        "check_sha1": {
            "21fdff3b0de78814c639f31869d0ca61f7f7173d": "Pass"
        },
        "check_sha256": {
            "31c287005379bf6273e7f2b91ae510aa55138366961e33e789caafda65ae5bb7": "Pass"
        },
        "check_sha512": {
            "235652516ae9f1daa2dc799d070071f38a8f39843240356f214327867fd708fa02682d841fd627f847963326a1c07449a7b56cd5a5e4b67264de38c3afcc7b27": "Pass"
        }
    }
}

the above test passed. This means all the expected data was found in the Cuckoo report. A report like the one above will be generated for each test file. There will also be a global report for each test task. This report contains the status for each test.

Global report example

    "summary": {
        "cuckoo_server": "127.0.0.1:9200",
        "end_result": "Passed",
        "percentage_passed": 100.0,
        "total_failed": 0,
        "total_passed": 1,
        "total_tests": 1
    },
    "tests": {
        "filetypes": {
            "test-javajar.json-176": {
                "machine_name": "w7cuckoo1",
                "result": "Passed"
            }
        }
    }
}

Why use this?

This tool makes it easier to run functional tests for Cuckoo. It can be used to see if the monitor is still detecting what should be detected. The goal is to have functional tests for a lot of scenarios and all supported analysis packages.

Another use of this tool is verifying Cuckoo setups. It is possible to use sets of tests to verify if the virtual machines for your Cuckoo instance are properly configured. An example of this would be verifying if Java, .NET, Adobe Reader, etc are installed.

How to use Cuckoobot

The functionality discussed in this post is the testing functionality. To use this, a few steps need to be taken.

Step 1

pip install cuckoobot

Step 2

Run Cuckoobot once so the working directory can be created. Cuckoobot will use ~/.cuckoobot as a working directory.

cuckoobot

Step 3

Tell Cuckoobot what the IP and API port of your Cuckoo server is.

Edit ~/.cuckoobot/config/cuckoobot.conf

# The Cuckoo server IP
cuckoo_server = 127.0.0.1

# The API port for the Cuckoo server
api_port = 8090

RicoVZ / cuckoo-unittest-docs