본문으로 바로가기



1. Introduction


이번에 소개할 내용은 Cuckoo Sandbox의 api.py를 이용한 api기능 사용 방법이다. Cuckoo 1.0에서 제공하는 api.py는 REST API로 curl로 요청을 보내고 curl로 데이터를 받아 올 수 있다. REST API의 상세한 내용은 위키피디아에서 볼 수 있으며, Cuckoo가 agent 와의 통신에 사용하는 XML-RPC 프로토콜도 REST API로 분류할 수 있다. REST API를 통하면, 어떤 언어를 사용하는 시스템이든 결과값을 데이터베이스화 하여 출력할 수 있다는 장점이 있어 Cuckoo를 손 쉽게 기능화 할 수 있다.


api.py를 사용하여 REST API를 이용하는 부분은 Cuckoo Documentation에 충분히 소개되어 있다. 이 포스팅은 실습을 통해서 실제 사용을 정리 해 볼 예정이다.


2. Installation


sudo apt-get install python-bottle

sudo apt-get install curl


Cuckoo를 설치하는 과정에 설치하는 python-bottle이 이 기능을 한다. Ubuntu 12.04 에서 curl은 설치되어 있지 않기에 추가로 설치할 필요가 있다.


3. Configuration


api.py를 기본값으로 실행하면 다음과 같이 WSGIRefServer가 시작된다. WSGIRef는 Web Server Gateway Interface의 약자로 웹 서버와 웹 애플리케이션의 인터페이스를 위한 파이썬 프레임워크이다.


api.py 실행api.py 실행


특정 HOST와 PORT를 사용하고 싶으면 -h 명령을 통해 사용방법을 확인 할 수 있다.



4. Starting



위 표와 같이 사용할 수 있다. POST는 Cuckoo에게 작업을 던지는 역할을 하고 GET은 결과를 반환받아 출력해 준다.


4.1. POST tasks/create/file


curl -F file=@/path/to/file http://localhost:8090/tasks/create/file


파일을 분석하기 위해서는 위와 같은 형태로 사용한다. 수정할 부분은 두 군데로 /path/to/file은 분석할 파일의 상대 경로, 절대 경로 둘다 사용할 수 있다. localhost:8090은 api.py를 사용할 때 설정한 HOST와 PORT를 사용하면 된다. 


curl -F file=@/path/to/file -F 'parameter=value' http://localhost:8090/tasks/create/file


추가로 파라미터를 입력하여 다양한 설정을 할 수 있다. 파라미터를 입력하기 위해서는 -F 옵션을 추가로 사용해야하며, 파일 분석에 사용되는 파라미터 리스트는 문서를 참고하길 바란다.


정상적으로 Cuckoo의 api.py 서버가 값을 받았다면 다음과 같은 응답을 받게 된다.


{

"task_id": task ID

}


task ID는 할당받은 ID이다. task ID는 자동으로 할당받는다.


4.2. POST tasks/create/url


curl -F url=@"http://www.example.co.kr" http://localhost:8090/tasks/create/file


url을 분석하기 위한 방법은 위와 같은 형태로 사용하며 파라미터는 POST file에서 사용하는 방법과 같으며, URL 분석에 사용되는 파라미터 리스트는 문서를 참고하길 바란다.


정상적으로 Cuckoo의 api.py 서버가 값을 받았다면 다음과 같은 응답을 받게 된다.


{

"task_id": task ID

}


task ID는 할당받은 ID이다. task ID는 자동으로 할당받는다.


4.3. GET tasks/list


curl http://localhost:8090/tasks/list


분석된 모든 task list를 보기 위한 방법이다. 파라미터로 limit과 offset이 있는데 여러가지 검색과 테스트를 해본 결과 사용 방법을 찾지는 못했다. 리스트는 최근 순서부터 차례대로 보여준다.


{

    "task": {

        "category": "file", 

        "machine": "", 

        "errors": [], 

        "target": "/home/hakawati/tools/cuckoo/web/tmp_uploads/tmpxzeT9Z/malware.exe", 

        "package": "", 

        "sample_id": 1, 

        "clock": "2014-05-02 17:13:09", 

        "guest": {

            "shutdown_on": "2014-05-02 17:14:36", 

            "task_id": 4, 

            "label": "cuckoo_01", 

            "manager": "VirtualBox", 

            "started_on": "2014-05-02 17:13:10", 

            "id": 4, 

            "name": "cuckoo1"

        }, 

        "custom": "", 

        "priority": 1, 

        "platform": "", 

        "options": "", 

        "status": "reported", 

        "enforce_timeout": false, 

        "timeout": 0, 

        "memory": false, 

        "tags": [], 

        "started_on": "2014-05-02 17:13:09", 

        "id": 4, 

        "added_on": "2014-05-02 17:13:09", 

        "completed_on": "2014-05-02 17:14:37"

    }

}


4.4. GET tasks/view


curl http://localhost:8090/tasks/view/task ID


특정 task를 보기 위한 방법이다. 정상적으로 응답을 받은 경우 해당 task ID 에 맞는 값만 읽어오게 된다.


{

    "task": {

        "category": "file", 

        "machine": "", 

        "errors": [], 

        "target": "/home/hakawati/tools/cuckoo/web/tmp_uploads/tmpxzeT9Z/malware.exe", 

        "package": "", 

        "sample_id": 1, 

        "clock": "2014-05-02 17:13:09", 

        "guest": {

            "shutdown_on": "2014-05-02 17:14:36", 

            "task_id": 4, 

            "label": "cuckoo_01", 

            "manager": "VirtualBox", 

            "started_on": "2014-05-02 17:13:10", 

            "id": 4, 

            "name": "cuckoo1"

        }, 

        "custom": "", 

        "priority": 1, 

        "platform": "", 

        "options": "", 

        "status": "reported", 

        "enforce_timeout": false, 

        "timeout": 0, 

        "memory": false, 

        "tags": [], 

        "started_on": "2014-05-02 17:13:09", 

        "id": 4, 

        "added_on": "2014-05-02 17:13:09", 

        "completed_on": "2014-05-02 17:14:37"

    }

}


4.5. GET tasks/delete


curl http://localhost:8090/tasks/delete/task ID


특정 task를 삭제하기 위해 사용한다. 설명과 같이 데이터베이스 및 결과 모두가 삭제된다. cuckoo/storage/ analyses 에 저장되는 해당 데이터들 또한 모두 삭제된다.


정상적으로 Cuckoo의 api.py 서버가 값을 받았다면 다음과 같은 응답을 받게 된다.


{

    "status": "OK"

}


4.6. GET tasks/report


curl http://localhost:8090/tasks/report/task ID/report type


분석 후 생성되는 레포트도 읽어들일 수 있다. 읽을 수 있는 레포트 종류는 다음과 같으며, 레포트 타입을 설정하지 않으면 기본으로 json 레포트를 읽어들인다. maec를 활성화하여 레포트를 받음에도 불구하고 진행되지 않았으며 metadata는 MMDef 레포트를 받는다면 받아 볼 수 있다.


  • json
  • html
  • maec
  • metadata
  • all
  • dropped


curl http://localhost:8090/tasks/report/task ID/[all/dropped] > sample.tar.bz2


all은 모든 결과 파일들을 tar.bz2로 반환하며, dropped는 dropped file들을 tar.bz2로 반환한다. 위와 같은 형태로 tar.bz2 형태의 파일로 저장한다. 해당 압축 파일을 풀면 다음과 같은 결과를 받을 수 있다.


- dropped 는 dropped file들을 받는다.


files/

files/2402537859/

files/2402537859/nsu1.tmp

files/2301924280/

files/2301924280/malware.exe

files/4160887562/

files/4160887562/CrackBiernkr.exe


- all은 모든 파일들을 받는다.


files/

files/2402537859/

files/2402537859/nsu1.tmp

files/2301924280/

files/2301924280/malware.exe

files/4160887562/

files/4160887562/CrackBiernkr.exe

dump.pcap

binary

reports/

reports/report.html

reports/report.metadata.xml

reports/report.json

reports/report.maec-4.0.1.xml

analysis.log

shots/

shots/0001.jpg

shots/0012.jpg

shots/0009.jpg

shots/0011.jpg

shots/0016.jpg

shots/0017.jpg

shots/0007.jpg

shots/0010.jpg

shots/0008.jpg

shots/0006.jpg

shots/0014.jpg

shots/0003.jpg

shots/0002.jpg

shots/0013.jpg

shots/0004.jpg

shots/0015.jpg

shots/0005.jpg

logs/

logs/424.bson

logs/3460.bson

logs/3832.bson


4.7. GET tasks/screenshots


wget http://localhost:8090/tasks/screenshots/task ID/screenshot number


스크린샷을 가져올때는 curl이 아닌 wget을 사용한다. task ID로 원하는 task를 선택한다. task ID 만을 선택했을 때 모든 스크린샷을 가져오고 특정 스크린샷을 가져온다면 스크린샷 번호를 넣으면 된다. 번호는 4자리 숫자로 구성되어 있다. 다만 이 기능은 제대로 구현되지 않아 확인하지 못했다.


4.8. GET files/view


세 가지 기능으로 구분하여 사용 할 수 있다.


md5

curl http://localhost:8090/files/view/md5/md5


sha256

curl http://localhost:8090/files/view/sha256/sha256


id

curl http://localhost:8090/files/view/id/id


이 기능은 cuckoo/storage/binaries 를 기준으로 한다. 즉, 중복된 데이터가 될 수 있는 task ID로 검색하는 것이 아니기 때문에 사용 시 주의 할 필요가 있다.


결과는 다음과 같은 형태를 따른다.


{

    "sample": {

        "sha1": "bb25c8d6c93624700147de5f1b16f2502d35fb59", 

        "file_type": "PE32 executable (GUI) Intel 80386, for MS Windows, Nullsoft Installer self-extracting archive", 

        "file_size": 140910, 

        "crc32": "1650B2C0", 

        "ssdeep": "1536:I3cpyORJLuB4P4AJJhgFfsVBIArvd6JbFkieyZKLkUyeG1rqG9gq9m0/26/K8Fp0:

I3c1fP4AJJFVBpbNVyekrLf/eOFBG", 

        "sha256": "eff9e2a241d6e351b01de5c6010d43c117ebbaa65e1a11116d44e1c74585d80b", 

        "sha512": "065eab27548ca6385b665a14e62239caab7da321f4991fe20b14f5b8701d1a40a0

f4b175a181950ed0860a8883e7a95abcb8e5a1cec60a83bcea59cd53af8b1d", 

        "id": 1, 

        "md5": "3988e1f461739033f48d27a357c25918"

    }

}


4.9. GET files/get


curl http://localhost:8090/files/get/sha256 > sample.exe


이 기능은 cuckoo/storage/binaries 에 선택한 sha256에 해당하는 악성코드를 가져오는 역할을 한다. cuckoo 공식 documentation에는 잘못 설명 되어 있다.


4.10. GET pcap/get


curl http://localhost:8090/pcap/get/id > dump.pcap


이 기능은 pcap을 가져오는 기능을 하지만 동작하지 않는다. cuckoo 공식 documentation에는 잘못 설명 되어 있다.


4.11. GET machines/list


curl http://localhost:8090/machines/list


이 기능은 agent 리스트를 가져와서 출력하는 역할을 한다.


결과는 다음과 같은 형태를 가진다. (설정한 가상머신은 한 대 이기에 한대만 출력되었다.)


{

    "machines": [

        {

            "status": "poweroff", 

            "locked": false, 

            "name": "cuckoo1", 

            "resultserver_ip": "10.0.2.15", 

            "ip": "172.16.0.101", 

            "tags": [], 

            "label": "cuckoo_01", 

            "locked_changed_on": "2014-05-02 17:14:37", 

            "platform": "windows", 

            "snapshot": null, 

            "interface": null, 

            "status_changed_on": "2014-05-02 17:14:36", 

            "id": 1, 

            "resultserver_port": "2042"

        }

    ]

}


4.12. GET machines/view


curl http://localhost:8090/machines/view/name


특정 한 대의 agent만 출력하려면 이 기능을 이용하면 된다. (설정한 가상머신이 한대이기에 machines/list와 동일한 결과를 보여주었다.)


4.13. GET cuckoo/status


curl http://localhost:8090/cuckoo/status


이 기능은 cuckoo의 상태를 출력해준다.


결과는 다음과 같은 형태를 가진다.


{

    "tasks": {

        "reported": 4, 

        "completed": 0, 

        "total": 4, 

        "running": 0, 

        "pending": 0

    }, 

    "version": "1.0", 

    "hostname": "hakawati-VirtualBox", 

    "machines": {

        "available": 1, 

        "total": 1

    }

}


5. ETC.


이 기능들은 REST API를 사용하며, 이는 기본적으로 http 통신을 하기 때문에 http 상태 코드를 이해하면 좀더 쉽게 사용 할 수 있다.


  • 200 성공 - 정상적으로 REST API 서버와 통신이 되었을 경우, 별도의 코드는 발생하지 않고 응답(request)를 받는다.
  • 404 에러 - 404는 요청한 페이지를 찾을 수 없다는 의미를 가지며, 동일하게 응답하지 못할 요청을 하게 되면 발생하게 된다.
  • 500 에러 - 500은 서버 내부 에러로 받아 들일 수 없는 파라미터를 입력하는 것과 같은 문제로 인해 발생한다.


6. Reference


http://ko.wikipedia.org/wiki/REST

http://ko.wikipedia.org/wiki/웹 서버 게이트웨이 인터페이스

http://docs.cuckoosandbox.org/en/latest/usage/api/

http://community.cuckoosandbox.org/posts/show/calling-the-rest-api-server/

저작자 표시 비영리 동일 조건 변경 허락
신고

댓글을 달아 주세요

  1. kliu 신고">2014.10.14 13:14 신고

    쿠쿠를 이용해 장기분석을 하려는 사람입니다. 설치 후 기본적인 것들은 잘 이용하고 있는데요. 혹시 장기간 분석하는 도중에 중간중간 DB에 쌓인 결과값들을 확인할 수 있는 방법이 있을까요? 예를 들어 월요일부터 토요일까지 일주일간 타임아웃을 줬다면 수요일이나 목요일쯤 그동안 쌓인 데이타를 확인할 수 있는...그런 방법이 있을까 여쭤봅니다 ^_^
    아 DB는 postgresql을 사용하고 있습니다.

    • BlogIcon hakawati 신고">2014.10.17 15:56 신고

      일반적인 장비의 대시보드 같은 부분이네요. 조건에 맞는 쿼리문과 별도의 코딩그리고 웹 인터페이스에 표현을 하는 부분까지 만드셔야 할 것 같아요. 기본적인 운영에서는 포함되어 있지 않은 기능 같습니다.

  2. kkkkk 신고">2014.10.29 15:25 신고

    웹에서 사용하려면 어떻게 해야하나요

티스토리 툴바