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의 약자로 웹 서버와 웹 애플리케이션의 인터페이스를 위한 파이썬 프레임워크이다.
특정 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/
'Information Security > OpenSource' 카테고리의 다른 글
| How to using volatility in Cuckoo Sandbox (2) | 2014.06.25 |
|---|---|
| How to install malcontrol (6) | 2014.05.15 |
| Using HPFClient Report within Cuckoo Sandbox (0) | 2014.04.15 |
| Using MMDef Report within Cuckoo Sandbox (0) | 2014.04.15 |
| Using MAEC Report within Cuckoo Sandbox (0) | 2014.04.14 |
