## https://sploitus.com/exploit?id=5EE2E47B-75F0-559E-9611-2D57E63C1641
## BlackBox Hunter Description
BlackBox Hunter is a black-box vulnerability analysis tool for `.deb` / `.rpm` software packages. Its goal is to decompress the package, perform static scanning, conduct AI-assisted binary analysis, merge results, perform PoC sandbox verifications, and generate reportsβall within a recoverable, verifiable, and auditable workflow. This directory itself constitutes the Skill package. The entry file is `SKILL.md`, and execution details are organized in `phases/`, `templates/`, `tools/`, `sandbox/`, and `tests/`.
## Applicable Scenarios
- Requires auditing of third-party `.deb` or `.rpm` packages without source code.
- Needs to utilize both traditional security tools and AI-based binary analysis to improve detection rates.
- Requires breaking down the scanning process into recoverable stages to avoid rerunning due to failures.
- Requires unifying outputs from different tools and analysis dimensions into structured JSON for subsequent merging, verification, and report generation.
- Requires controlled PoC verifications of high-value findings within isolated Docker sandboxes.
## Not Applicable Scenarios
- Projects where source code auditing is prioritized. This Skill primarily targets black-box package scans.
- Tasks requiring dynamic network attacks, real external service probing, or lateral movement verification.
- Processes where AI-based inference is not allowed in vulnerability assessment. Track B outputs need to be used in conjunction with evidence and confidence levels.
## Core Capabilities
### 1. Software Package Profiling
**Phase 0:** Responsible for decompressing the package and generating a profile:
- Generates a unique `scan_id` in the format `BBH-YYYYMMDD-`.
- Conducts disk space pre-checking, estimating the required working directory based on `package size * 5 + 1 GiB`.
- Identifies package type, architecture, ELF binaries, scripts, configuration files, systemd units, and potential entry points.
- Generates `target_profile.json`, `scan_strategy.json`, `coverage_plan.json`, `sandbox_status.json`, and `scan_state.json`.
### 2. Track A: Traditional Tool Scanning
**Track A** uses deterministic tools for static analysis. Common tools include:
- `cve-bin-tool`: CVE clues and dependency risks.
- `checksec`: ELF hardening checks.
- `cwe_checker`: Binary CWE pattern recognition.
- `strings` + YARA: Dangerous functions, hardcoded keys, suspicious configuration patterns.
- `lintian` / `rpmlint`: Debian/RPM package metadata and maintenance script checks.
Track A outputs are encapsulated in `track_findings.json`, with finding IDs using the format `TA-NNN`.
### 3. Track B: AI-Assisted Binary Analysis
**Track B** focuses on AI-assisted analysis, targeting high-risk functions and entry points. Currently, **Phase 1b** covers 7 dimensions:
- `dangerous_functions`: Dangerous function calls.
- `input_validation`: Input validation and boundary checks.
- `control_flow`: Abnormal control flows and state transitions.
- `memory_management`: Memory lifecycle, out-of-bound accesses, and release issues.
- `privilege_model`: Permission boundaries, setuid, service users, and sensitive operations.
- `protocol_parsing`: Protocol parsing, file format parsing, and length field handling.
- `hardcoded_config`: Hardcoded credentials, default keys, and dangerous configurations.
Supported analysis engines include Ghidra headless, radare2, and objdump fallback. Track B outputs are also in `track_findings.json`, with finding IDs using the format `TB-NNN`.
### 4. Result Merging and Confidence Scoring
**Phase 2** combines Track A and Track B outputs into `merged_findings.json` and generates `coverage_report.json`. The merging logic focuses on:
- Deduplication of the same binary, same CVE/CWE, same function, same address offset, or equivalent titles.
- Retaining `dedup_info.merged_from` to avoid losing original sources.
- Adjusting confidence levels based on evidence strength, cross-track consistency, architecture fallbacks, and offline CVE databases.
### 5. Sandbox PoC Verification
**Phase 3** verifies reproducible findings within a restricted Docker environment:
- Uses `poctest` with non-privileged users inside the container.
- Disables networking with `network_mode: none`.
- Limits system calls using seccomp profiles.
- `run_poc.sh` handles timeout, output directory, and exit code collection.
- The target package is mounted read-only, and verification outputs are written to independent scratch/output directories.
The verification results are written into `verified_findings.json`. ### 6. Report Generation
Phase 4 generates the final report based on the verification results, coverage metrics, status files, and original logs. The report template is located in `templates/report_summary.md`, covering the following sections:
- Executive summary.
- Scope and environment.
- Coverage metrics.
- Vulnerability findings.
- Constraints and follow-up recommendations.
## Directory Structure
```text
blackbox-hunter-skill/
βββ SKILL.md # Instructions for using the tool
βββ README.md # Chinese user guide
βββ phases/ # Manual for each phase
β βββ phase-0-profile.md
β βββ phase-1a-toolscan.md
β βββ phase-1b-ai-analysis.md
β βββ phase-2-merge.md
β βββ phase-3-verify.md
β βββ phase-4-report.md
βββ templates/ # JSON schemas and report templates
βββ tools/
β βββ tool_registry.json # Tool registry
β βββ install.sh # Assistant script for tool detection and installation
β βββ ghidra/DecompileFunction.java
β βββ rules/ # YARA rules
βββ sandbox/ # PoC sandbox configuration
βββ references/ # References for CWE and tool usage
βββ tests/ # Tests for schemas, scripts, YARA, and smoke tests
```
## Data Flow
```text
Input packages
-> Phase 0: target_profile / scan_strategy / coverage_plan / scan_state
-> Phase 1a: track_a_findings
-> Phase 1b: track_b_findings
-> Phase 2: merged_findings / coverage_report
-> Phase 3: verified_findings
-> Phase 4: final report
```
All scan results are stored by default in the following directory:
```text
$WORKSPACE//
```
`scan_state.json` is the core file for resume scanning and state restoration. ## Key JSON Contracts
The schemas in `templates/` serve as formal contracts for data exchange between agents:
- `finding.json`: Unified format for vulnerability findings, including `verification`, `remediation`, and `references`.
- `target_profile.json`: Package profiling, binary list, and attack surface.
- `scan_strategy.json`: Scanning mode, tool plan, and Track B focus area.
- `coverage_plan.json`: Coverage targets and Track assignments.
- `scan_state.json`: Phase state machine, error logs, and resume information.
- `sandbox_status.json`: Sandbox availability and constraints.
- `track_findings.json`: Outputs for Track A/Track B.
- `merged_findings.json`: Deduplicated and merged results.
- `coverage_report.json`: Coverage report.
- `verified_findings.json`: Findings after PoC verification. Only two prefixes are allowed for finding IDs:
- `TA-NNN`: Traditional tool scanning for Track A.
- `TB-NNN`: AI-based binary analysis for Track B.
```
## State Machine and Resume Scanning
The `SKILL.md` file uses `scan_state.json` to track phase states:
```text
idle
-> phase_0_running
-> phase_0_done
-> track_a_running + track_b_running
-> track_a_done + track_bdone
```
-> phase_2_running
-> phase_2_done
-> phase_3_running
-> phase_3_done
-> phase_4_running
-> completed
When resuming scanning, verify `scan_state.json` first, then check the required outputs for each completed phase. If a phase has a status of `failed`, or if the output is missing/invalid, resume from that phase. Outputs from successfully completed phases should not be overwritten directly; reruns should be recorded in `reruns/`, and only after verification can they be considered official outputs. ## Tool Dependencies
Basic verification requires:
- `bash`
- `python3`
Actual scans will use the following tools as needed:
- `cve-bin-tool`
- `checksec`
- `cwe_checker`
- `binwalk`
- `yara`
- `lintian`
- `rpmlint`
- `radare2`
- `ghidra`
- `docker` or `podman`
Instructions for tool registration and installation can be found in `tools/tool_registry.json` and `tools/install.sh`. If an optional tool is missing, the process should record the reason for the downgrade, rather than producing empty results silently. ## Quick Verification
Run from the root directory of the repository:
```bash
bash blackbox-hunter-skill/tests/run_all_tests.sh
```
This script will execute:
- `validate_rules.sh`: YARA rule smoke test.
- `validate_schemas.sh`: JSON Schema and fixture verification.
- `validate_scripts.sh`: Shell script syntax and phase documentation checks.
- `smoke_test.sh`: Minimum smoke tests; if `dpkg-deb` is not available on the local machine, the fixture package building will be skipped. You can also run these steps separately:
```bash
bash blackbox-hunter-skill/tests/validate_schemas.sh
bash blackbox-hunter-skill/tests/validate_scripts.sh
bash blackbox-hunter-skill/tests/validate_rules.sh
bash blackbox-hunter-skill/tests/smoke_test.sh
```
## How to Use
In environments that support Codex Skills, use `blackbox-hunter-skill/` as a skill package. When calling it, provide the target package path and scanning mode, for example:
```text
Use blackbox-hunter to scan /path/to/package.deb, with the mode βstandardβ.
```
When resuming an existing scan, provide the path to `scan_state.json`:
```text
Use blackbox-hunter to continue scanning from /workspace/BBH-20260627-a1b2c3/scan_state.json.
```
Executing a proxy should load the phase documents under `phases/` according to the sequence in `SKILL.md`, and validate the JSON output after each phase. ## Security Guidelines
- **Track A** and **Track B** should focus on static analysis only; untrusted logic in the target package should not be executed.
- **PoC** verifications must occur in the restricted environment defined by `sandbox/`.
- High-risk or destructive PoCs require manual confirmation before execution.
- Network probing is disabled by default; external probing is not used as a prerequisite for verification.
- The offline CVE database is available but may reduce the confidence of CVE-related findings. ## Output Interpretation Recommendations
- `severity` indicates potential impact; it does not equal verified exploitability.
- `confidence` indicates the strength of evidence, which depends on tool coverage, architecture support, and consistency with other tracks.
- `verification.poc_status` represents the PoC verification status, which may be `untested`, `verified`, `failed`, or `skipped`.
- AI outputs for Track B must be supported by evidence such as functions, addresses, decompiled segments, strings, configurations, or tool outputs. ## Current Limitations
- Multi-architecture support uses branching and downgrading strategies; architectures other than `x86_64` or `aarch64` may only allow string analysis, YARA, objdump, and metadata analysis.
- External tools like Ghidra, radare2, and Docker are not included with the skill and need to be installed in the running environment.
- `tests/` primarily verifies the contract of skill files and data; it does not represent end-to-end vulnerability scanning of actual software packages.
- **PoC** sandboxes are used to reduce risk; they should not be considered strong isolation security boundaries.