대규모 포트 탐색, 호스트 탐색, 배너 그래빙, 그리고 내부 또는 외부 네트워크 전반에 걸친 NSE 기반 취약점 스캐닝을 위한 masscan 및 nmap의 Python 래퍼입니다.
이 스크립트는 masscan과 nmap의 래퍼입니다. nmap은 호스트 탐지와 (소규모 스캔의 경우) 포트 탐지, 서비스 배너 그래빙, NSE 스크립트를 처리합니다. Masscan은 원시 속도가 중요한 대규모 포트 탐지에 사용됩니다. 두 도구 모두 선호하는 패키지 관리자나 소스에서 설치하세요.
Python 3.8+가 필요합니다 (pyproject.toml의 requires-python; CI 최소 버전은 3.8).
SpooNMAP은 체크아웃에서 바로 실행할 수 있으며 — 설치 단계가 필요하지 않습니다. 아래 "사용법"을 참조하세요 — 또는 uv를 사용하여 독립 실행형 명령으로 설치할 수 있습니다:
uv tool install git+https://github.com/trustedsec/spoonmap
이렇게 하면 spoonmap 실행 파일이 PATH에 추가되므로, 저장소를 복제하고 ./spoonmap.py를 실행하는 대신 어느 디렉터리에서든 spoonmap으로 호출할 수 있습니다. PyPI 패키지는 없습니다 — 이 프로젝트는 pypi.org에 게시된 적이 없으며, 위 명령은 대신 git 저장소에서 직접 설치합니다. 위의 전체 git+https://... 형식을 사용하고, uv tool install spoonmap만 사용하지 마세요. PyPI에서 그 이름이 현재든 미래든 무엇을 가리키든, 이 프로젝트가 아닙니다.
최신 커밋으로 업데이트하려면:
uv tool upgrade spoonmap
이런 방식으로 설치한다고 해서 SpooNMAP이 자체 완결형 스캐너가 되는 것은 아닙니다:
masscan과 nmap은 여전히 별도로 설치해야 하는 시스템 도구입니다
(위의 "Dependencies" 참조). 체크아웃에서 실행할 때와 정확히 마찬가지입니다 —
uv tool install은 SpooNMAP 자체의 Python 코드와 번들된 NSE 스크립트만
패키징할 뿐, 셸을 통해 호출하는 외부 바이너리는 패키징하지 않습니다.
이 방식으로 설치하기 전에 알아둘 만한 한 가지: 설치된 spoonmap의
Python 모듈은 uv가 관리형 도구 환경을 둔 위치에 존재합니다 — 설정
파일이나 스캔 출력을 찾아볼 만한 디렉터리가 아닙니다. 바로 이 시나리오가
아래 "Where Files Live" 섹션에서 다루는 내용입니다 — 현재 디렉터리를
기준으로 무엇이 해석되는지, 그리고 그 이유에 대해서는 해당 섹션을 읽어
보세요. uv tool install로 설치해도 규칙은 바뀌지 않습니다. 다만 그
규칙이 중요해질 뿐입니다. 설정이나 출력 경로가 습관적으로 되돌아갈
체크아웃 디렉터리가 더 이상 남아 있지 않기 때문입니다.
스크립트를 실행하기만 하면 필요한 모든 옵션을 묻는 프롬프트가 표시됩니다.
config.json, 대상/제외 파일, 스캔 출력은 모두 명령을 실행한 디렉터리를
기준으로 해석됩니다 — 출력이 예상한 위치에 없을 경우, 특히 SpooNMAP을
자체 디렉터리 밖에서 경로로 호출하는 데 익숙하다면 아래 "Where Files
Live"를 참조하세요.
uv를 사용한다면 별도의 가상 환경 없이 실행할 수 있습니다:
uv run spoonmap.py
스크립트가 실행 가능한 경우 직접 호출하세요:
# ./spoonmap.py
________ _____ _______ _________________
__ ___/______________________ | / /__ |/ /__ |__ __ \
_____ \___ __ \ __ \ __ \_ |/ /__ /|_/ /__ /| |_ /_/ /
____/ /__ /_/ / /_/ / /_/ / /| / _ / / / _ ___ | ____/
/____/ _ .___/\____/\____//_/ |_/ /_/ /_/ /_/ |_/_/
/_/
Service Categories (comma-separated numbers, default: All)
(1) Web [80, 443, 7001, 7002, 8000, 8080, 8081, 8443, 8888, 9090, 10443]
(2) Database [1433, U:1434, 1521, 3306, 5432, 6379, 9200, 27017]
(3) Remote Management [22, 23, 3389, 5900, 5901, 6129, 1723, 5985, 5986]
(4) Email [25, 110, 143, 465, 587, 993, 995]
(5) LDAP [389, 636]
(6) Network Infrastructure [53, 179, U:500, U:161, U:623, U:631, U:1194, 1194]
(7) File Transfer [21, 111]
(8) SMB [445, 135, 139, U:137]
(9) Specialized [1090, 3300, 4786, 6970, 2375, 4243, 9100, 8530, 8531]
(10) Containers & Debuggers [2377, 10250, 8001, 9229, 2345, 5005, 61616, 8009, 6000]
(11) Local LLM [11434, 1234, 7860, 5000, 5001, 1337, 3000, 8000, 8080]
(12) Full Port Scan [1-65535, TCP only — no UDP]
(c) Custom Port Scan [enter your own comma-separated ports]
(The Full Port Scan number increments automatically with the number of categories.)
**Full Port Scan is TCP only.** It sweeps TCP 1-65535 and runs no UDP discovery at
all, so every `U:` port listed in the categories above — SNMP (U:161), IKE (U:500),
IPMI (U:623), IPP (U:631), OpenVPN (U:1194), NetBIOS (U:137), SQL Browser (U:1434) —
is skipped, along with the NSE scripts and findings that depend on them. It is
*wider* than All on TCP and *narrower* on UDP. For both, run All and Full as two
passes, or use the Custom option with the UDP ports appended
(e.g. `1-65535,U:161,U:500,U:623`).
Which categories would you like to scan (e.g. 1,3 — default: All)?
Would you like to enumerate service banners for any identified services (default: Yes)?
Would you like to run NSE security scripts on identified services (default: No)?
Target Scan
(1) External
(2) Internal
Is this an internal or external scan (default: External)?
How fast would you like to scan (default: 20000 packets/second)?
Please enter the full path for the file containing target hosts (default: /opt/spoonmap/ranges.txt):
Would you like to exclude any hosts? (default: No)
Run host discovery before port scanning (default: Yes)?
Tune advanced settings (nmap threads, masscan batch size, nmap work-unit threshold)? (default: No)
config.json 파일을 생성하여(config.json.sample 기반) 모든 프롬프트를 건너뛸 수도 있습니다:
{
"scan_categories": ["Web", "Database", "Remote Management"],
"banner_scan": "True",
"script_scan": "False",
"host_discovery": "True",
"target_scan": "Internal",
"max_rate": "2000",
"target_file": "ranges.txt",
"output_path": "./",
"exclusions_file": "exclusions.txt",
"nmap_threads": 5,
"masscan_batch_size": 5,
"nmap_threshold": 5000000
}
모든 카테고리를 스캔하려면 "scan_categories": "All"로 설정하십시오.
모든 65535개 TCP 포트를 스캔하려면 "scan_categories": "Full"로 설정하십시오 — 이는 TCP 전용이며 UDP 탐색을 수행하지 않는다는 점에 유의하십시오.
완전히 사용자 정의된 포트 목록을 사용하려면 scan_categories를 생략하고 대신 "dest_ports": ["80","443","U:53"]을 사용하십시오.
UDP 포트는 U: 접두사로 지정합니다 (예: "U:53").
대화형 프롬프트에 응답하면 선택한 옵션이 스캔 시작 전에 config.json에 기록됩니다. 생성된 파일은 config.json.sample과 동일한 방식으로 각 편집 가능한 필드를 문서화하며, __generated_by_prompts__ 마커 키를 포함합니다. 이는 중단된 대화형 스캔을 config 기반 스캔과 동일한 방식으로 재개할 수 있음을 의미합니다 — --resume으로 다시 실행하기만 하면 모든 프롬프트가 건너뛰어집니다.
output_path에서 이전 스캔의 출력이 감지되면 도구는 세 가지 선택지를 제공합니다: [d]elete (이전 출력을 제거하고 새로 시작), [a]ppend (이전 출력을 유지하되 모든 단계를 다시 실행), 또는 [r]esume (이전 출력을 유지하고 이미 완료된 작업을 건너뜀, 정확히 --resume 플래그와 동일하게).
재실행 시 옵션 변경. [d]elete 또는 [a]ppend를 선택하면 저장된 config.json 값이 기본값으로 미리 채워진 상태로 모든 옵션을 다시 묻습니다 — 따라서 프롬프트에서 Enter를 누르면 이전 스캔이 재현되며, 관심 있는 포트, 속도, 대상만 변경할 수 있습니다. [r]esume은 동일한 스캔을 계속하는 것이므로 프롬프트를 건너뜁니다. 재프롬프트는 도구가 생성한 config.json(즉 __generated_by_prompts__를 포함하는 파일)에만 적용됩니다. 직접 작성한 config는 위에서 설명한 모든 프롬프트 건너뛰기 동작을 엄격히 유지합니다. 옵트아웃하려면 해당 키를 제거하거나, config.json을 완전히 삭제하여 처음부터 시작하십시오.
프롬프트에 다시 응답하면 config.json을 덮어쓰는 것이 아니라 병합하여 다시 작성합니다: 파일에 직접 추가한 모든 키는 보존됩니다.
대상 파일을 편집하지 않고 단일 주소(또는 짧은 목록)를 스캔하려면 --target을 사용하십시오:
./spoonmap.py --target 10.0.0.5
./spoonmap.py --target 10.0.0.0/24
./spoonmap.py --target 10.0.0.5,10.0.1.0/24,10.0.2.1-10.0.2.9
값은 대상 파일의 한 줄이 허용하는 모든 형식을 받습니다 — 단일 IP, CIDR, A-B 범위, 또는 address netmask — 쉼표로 구분됩니다. 이는 스캔이 시작되기 전에 검증됩니다: 잘못된 형식이거나 IPv6 주소인 경우, 빈 대상 집합에 대해 문제없이 실행되는 대신 문제가 되는 항목을 명시하며 0이 아닌 종료 코드로 중단됩니다.
--target은 config.json의 target_file과 대화형 프롬프트 모두보다 우선하므로, 그 외에는 완전히 비대화형인 실행에서도 작동합니다. 주소는 output_path의 cli_targets.txt에 기록됩니다; ranges.txt는 절대 수정되지 않으므로 참여 범위 파일이 그대로 유지되고, 각 실행이 실제로 무엇을 대상으로 했는지에 대한 기록이 디스크에 남습니다.
--target=10.0.0.5 (=를 플래그와 값 사이에 사용)도 이제 작동합니다. --target 10.0.0.5와 동일하며, --cleanup=/path/to/output도 마찬가지입니다. 이 도구가 argparse로 전환되기 전에는 --flag=value 형식이 수작업으로 작성된 '--flag' in sys.argv 검사 중 어느 것에도 일치하지 않아서, --target=10.0.0.5는 완전히 조용히 무시되었고 스캔은 실제로 요청한 주소 대신 ranges.txt에 대해 실행되었습니다 — 이는 예전 버그가 단순히 플래그를 무시한 것이 아니라 조용히 범위를 변경한 유일한 사례입니다.
프롬프트 없이 중단된 스캔을 재개하려면 --resume 플래그를 사용하십시오:
./spoonmap.py --resume
# or
uv run spoonmap.py --resume
--resume은 출력이 resolved_targets.txt보다 최신인 완료된 호스트 검색 및 포트 검색을 재사용하고, 기존 라이브 호스트 목록을 로드하여 중단된 지점부터 계속합니다. resolved_targets.txt는 해석된 대상 집합이 실제로 변경될 때만 다시 작성되므로, 변경되지 않은 ranges.txt로 재개하면 검색을 완전히 건너뜁니다(재스캔 없음). 마지막 실행 이후 ranges.txt가 변경된 경우, resolved_targets.txt는 더 새로운 타임스탬프로 다시 작성되며, 이제 그보다 오래된 검색 출력(호스트 및 포트)은 자동으로 다시 실행되어 새로 추가된 범위를 놓치지 않습니다. nmap 배너/스크립트 결과는 항상 재개됩니다(기존 nmap_results/portN.xml 파일은 무조건 건너뜁니다). 재개는 config.json에서 "resume": "True"로도 활성화할 수 있습니다.
스캔 데이터를 비대화형으로 제거하려면 --cleanup 플래그를 사용하십시오:
# Path taken from output_path in config.json
./spoonmap.py --cleanup
# or
uv run spoonmap.py --cleanup
# Or specify the directory explicitly
./spoonmap.py --cleanup /path/to/output
설치된 버전을 출력하려면: