🦅 Hawk‑i

Holistic Analysis for Web3 Kode & Infrastructure
Open‑source, privacy‑first security intelligence for smart contracts

---

📖 Table of Contents

• What is Hawk‑i?
• Features
• Quick Start
• Operational Modes
• Advanced Usage
  • Audit‑Grade Reporting
  • Security Score
  • Guided Remediation
  • Telemetry (Opt‑In)
  • CLI Reference
  • CI/CD Integration
  • Ecosystem Integrations
• Demo Suite
• Project Structure
• Contributing
• License
• Acknowledgements
• Roadmap
• Contact

---

🦅 What is Hawk‑i?

Hawk‑i is an open‑source security intelligence platform for Web3 smart contracts. It evolves beyond a simple scanner into a complete audit‑grade system that detects, simulates, scores, and helps fix vulnerabilities – all while respecting your privacy.

Whether you're a solo developer, an auditor, or a protocol team, Hawk‑i integrates into your workflow to provide continuous, actionable security insights.

Key differentiators:

• Hybrid analysis – static rules + AI reasoning + live exploit simulation.
• Professional reporting – executive summaries, risk scores, charts, and per‑finding remediation.
• Privacy by design – runs locally; no code is ever sent to external servers (AI uses your own API keys).
• Extensible – drop‑in rules, attack scripts, and templates.

---

✨ Features

Core Capabilities

• 🔍 Repository Intelligence – Parse and index Solidity files from local folders or remote Git repos (GitHub, GitLab, etc.).
• 📦 Static Rule Engine – Detect 30+ common vulnerabilities (reentrancy, access control, integer overflows, oracle manipulation, etc.) with an extensible rule system.
• 🧠 AI Reasoning – Leverage LLMs (Gemini, OpenAI, Anthropic, local Ollama) to uncover logic flaws, economic exploits, and governance risks that static analysis misses.
• 💣 Exploit Simulation Sandbox – Automatically deploy contracts in an isolated Docker environment and run attack scripts to validate vulnerabilities; results influence your risk score.
• ⏱️ Continuous Monitoring – Watch repositories and deployed contracts for changes, and get alerts via file or console.

v0.7.0 – Intelligence & Reporting Upgrade

• 📊 Audit‑Grade Reporting (ARS v2) – Generate professional reports with executive summary, security score (0–100), severity charts, and per‑finding remediation.
• 🛡️ Guided Remediation Engine – Every finding includes a context‑aware fix snippet, auto‑populated with your code’s variable names.
• 📈 Security Score – A deterministic 0–100 score based on finding severity and exploit success, with clear risk bands.
• 📡 Telemetry (Opt‑In) – Anonymous usage metrics to demonstrate ecosystem impact (no code, no repo names).
• 🧩 Expanded Vulnerability Library – 30 fully documented vulnerabilities, each with detection, exploit script, and fix template.

---

🚀 Quick Start

Installation

Option 1: Install from PyPI (recommended)

pip install hawki

Option 2: Use Docker

docker pull 0xsemantic/hawki:latest
docker run --rm -v $(pwd):/repo 0xsemantic/hawki scan /repo

Option 3: Install from source

git clone https://github.com/0xSemantic/hawki.git
cd hawki
pip install -e .

Basic Scan

hawki scan /path/to/your/project

This runs static rules only (Minimal mode) and outputs a simple JSON report (legacy format). For the new audit‑grade report, use --format.

Full Audit with AI + Sandbox

hawki scan /path --ai --ai-model openai/gpt-4 --api-key YOUR_KEY --sandbox --format pdf --telemetry

• --ai enables AI reasoning (requires an API key).
• --sandbox runs exploit simulations (requires Docker).
• --format pdf generates a professional PDF report.
• --telemetry opts in to anonymous usage stats.

Generate a Report from Previous Scan

hawki report --input findings.json --format html --output report.html

View Security Score

hawki score findings.json

Show Local Telemetry

hawki metrics

Monitor a Repository

hawki monitor /path/to/repo --interval 60 --alert-log alerts.txt

---

⚙️ Operational Modes

Hawk‑i adapts to your environment and privacy needs:

Mode	Static Rules	AI	Sandbox	Docker Required
Minimal	✅	❌	❌	❌
Enhanced	✅	✅	❌	❌
Full Audit	✅	✅	✅	✅

Reports indicate which mode was used and adapt content accordingly (e.g., omit exploit steps if sandbox disabled).

---

🔧 Advanced Usage

Audit‑Grade Reporting

The hawki scan command with --format generates a report using the new Audit‑Grade Report System (ARS v2). Reports include:

• Executive Summary – total contracts, severity counts, security score, risk classification, mode used.
• Vulnerability Breakdown – pie chart (severity) + bar chart (type) + fallback table.
• Per‑Finding Details – title, severity, file/line, vulnerable code, recommended fix, explanation, impact, exploit steps (if sandbox succeeded).
• Simulation Metrics – success rate, balance deltas, gas used.

Formats: Markdown (default), JSON, HTML, PDF (optional dependencies).

Example Markdown snippet:

## 🔍 Detailed Findings
### F001: Reentrancy in withdraw() (CRITICAL)
- **File:** contracts/Vault.sol
- **Line:** 42

**Vulnerable Code:**
```solidity
function withdraw() external {
    uint bal = balances[msg.sender];
    (bool success,) = msg.sender.call{value: bal}("");
    require(success);
    balances[msg.sender] = 0;
}

Recommended Fix:

function withdraw() external nonReentrant {
    uint bal = balances[msg.sender];
    balances[msg.sender] = 0;
    (bool success,) = msg.sender.call{value: bal}("");
    require(success);
}

Explanation: The function makes an external call before updating state, allowing reentrancy. Impact: An attacker can drain all funds. Exploit Reproduction Steps:

• Exploit succeeded using script: reentrancy_attack.py
• Before balance: 1000000000000000000
• After balance: 0
• Gas used: 120000
• Transaction hash: 0xabc...

### Security Score

The security score is a **deterministic 0–100** number computed as:

- Base: 100
- Deductions per finding:
  - Critical: -15
  - High: -8
  - Medium: -4
  - Low: -1
- If sandbox enabled: **-5** for each successfully reproduced exploit (capped).

**Risk Bands:**

| Score  | Classification |
|--------|----------------|
| 90–100 | Secure         |
| 75–89  | Minor Risk     |
| 50–74  | Moderate Risk  |
| 25–49  | High Risk      |
| 0–24   | Critical Risk  |

Use `hawki score findings.json` to see the score without generating a full report.

### Guided Remediation

Every finding now includes a `fix_snippet` populated by the **Remediation Engine**. The engine uses templates and AST context to generate accurate fixes. For example, a reentrancy finding might include:

```solidity
// Vulnerable code
function withdraw() external {
    uint amount = balances[msg.sender];
    (bool success, ) = msg.sender.call{value: amount}("");
    require(success);
    balances[msg.sender] = 0;
}

// Recommended fix
function withdraw() external nonReentrant {
    uint amount = balances[msg.sender];
    balances[msg.sender] = 0;
    (bool success, ) = msg.sender.call{value: amount}("");
    require(success);
}

Telemetry (Opt‑In)

When you run hawki scan --telemetry, Hawk‑i collects anonymous data:

• Total scans performed
• Findings per severity
• Simulation success rate (if sandbox enabled)
• Hawk‑i version
• Execution mode

Data is stored locally in ~/.hawki/metrics.json and can be viewed with hawki metrics. If you opt in, aggregated statistics may be sent to a public endpoint to power the community metrics badge. No source code, repository names, or IPs are ever collected.

View your metrics:

hawki metrics

Example output:

Total scans: 42
Total findings: 87 (Critical: 12, High: 23, Medium: 31, Low: 21)

CLI Reference

The main command is hawki. Available subcommands:

Subcommand	Description
scan	Perform a one‑time security scan.
monitor	Continuously monitor a repository or contract.
report	Generate a report from existing findings.
score	Calculate the security score from a findings file.
metrics	Display local telemetry statistics.
simulate	Run a specific exploit simulation (advanced).

hawki scan options:

hawki scan <target> [options]
  -v, --verbose               Enable debug logging
  -o, --output-dir DIR         Report output directory (default: ./hawki_reports)
  --ai                         Enable AI reasoning
  --ai-model MODEL              LLM model (e.g., openai/gpt-4)
  --api-key KEY                 API key for LLM
  --sandbox                     Run exploit simulation (requires Docker)
  --format {md,json,html,pdf}   Output report format (if omitted, legacy JSON)
  --telemetry                   Opt in to anonymous usage metrics

hawki report options:

hawki report [options]
  -i, --input FILE    Findings JSON file (default: latest)
  -o, --output-dir DIR Output directory
  -f, --format FORMAT  Output format (md, json, html, pdf)

hawki score:

hawki score findings.json [-v]

hawki metrics:

hawki metrics [-v]

CI/CD Integration

Hawk‑i provides a dedicated script scripts/ci_pipeline.py that auto‑detects GitHub Actions or GitLab CI and formats output accordingly.

GitHub Actions example (.github/workflows/hawki.yml):

name: Hawk-i Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Hawk-i
        run: pip install hawki
      - name: Run Hawk-i CI
        run: python scripts/ci_pipeline.py .

The script exits with code 1 if any HIGH severity findings are detected, allowing you to fail the pipeline.

GitLab CI example (.gitlab-ci.yml):

hawki-scan:
  image: python:3.11
  before_script:
    - pip install hawki
  script:
    - python scripts/ci_pipeline.py .
  artifacts:
    reports:
      codequality: gl-code-quality-report.json

Ecosystem Integrations

Use the helper script scripts/deploy_helpers.py to integrate with popular development tools.

Foundry

python scripts/deploy_helpers.py foundry /path/to/forge-project --ai

Hardhat

python scripts/deploy_helpers.py hardhat /path/to/hardhat-project

Remix

python scripts/deploy_helpers.py remix /path/to/remix-workspace

Generate a human‑readable audit report

python scripts/deploy_helpers.py readme /path/to/report.json --output AUDIT.md

---

🧪 Demo Suite

We’ve built a dedicated demo suite of intentionally vulnerable contracts to help you understand Hawk‑i’s capabilities and to test your contributions.

The suite includes 30 vulnerable contracts, one for each rule, covering:

• Reentrancy
• Access control bypass
• Delegatecall misuse
• Oracle manipulation
• Flash loan attacks
• Governance vote manipulation
• Signature replay
• Integer overflows
• And more…

Quick Demo (with Docker)

docker build -f demo/Dockerfile.demo -t hawki-demo .
docker run --rm hawki-demo

Manual Demo

cd demo
npm install           # install Hardhat dependencies
npx hardhat node      # start local blockchain (keep open)
# In another terminal:
npx hardhat run scripts/deploy.js --network localhost
hawki scan . --ai --sandbox --format html --telemetry

See the demo README for detailed instructions and expected output.

---

📁 Project Structure

hawki/
├── core/
│   ├── repo_intelligence/          # Repo cloning & Solidity parsing
│   ├── static_rule_engine/         # Static analysis & dynamic rule loading (30+ rules)
│   ├── ai_engine/                   # LLM orchestration & prompt management
│   ├── exploit_sandbox/             # Docker‑based exploit simulation
│   ├── remediation_engine/          # Context‑aware fix snippet generation
│   ├── telemetry/                    # Opt‑in anonymous metrics
│   ├── monitoring/                   # Continuous monitoring & alerts
│   └── data_layer/                   # Report generation (ARS v2) & persistence
├── cli/                              # Command‑line interface
├── scripts/                          # CI/CD and integration helpers
├── docker/                           # Dockerfile and compose
├── demo/                             # Vulnerable contracts for testing
├── tests/                            # Unit tests
├── pyproject.toml                    # Package metadata
├── CONTRIBUTING.md                    # Contribution guidelines
├── CONTRIBUTORS.md                    # List of contributors
└── README.md                          # This file

---

🤝 Contributing

We welcome contributions from the community! Whether you're fixing a bug, adding a new rule, or improving documentation, your help makes Hawk‑i better for everyone.

Please read our Contributing Guidelines to get started. All contributors are recognised in CONTRIBUTORS.md – we use the All Contributors specification.

---

📄 License

Hawk‑i is released under the MIT License.

---

🙏 Acknowledgements

Hawk‑i builds upon excellent open‑source projects:

• tree‑sitter and tree‑sitter‑solidity for parsing.
• LiteLLM for unified LLM access.
• Docker for sandboxing.
• Web3.py for blockchain interaction.
• GitPython for repository handling.
• matplotlib for chart generation (optional).
• Jinja2 for templated reports.

Special thanks to all contributors and the Web3 security community.

---

🛣️ Roadmap

• Phase 1 – Repository intelligence + static rule engine
• Phase 2 – AI reasoning with LiteLLM
• Phase 3 – Exploit simulation sandbox
• Phase 4 – Continuous monitoring & alerts
• Phase 5 – CI/CD & ecosystem integrations
• Phase 6 – Deployment (PyPI, Docker, CLI)
• Phase 7 – v0.7.0 Intelligence & Reporting Upgrade
  • Audit‑grade reporting (ARS v2)
  • 30 vulnerability rules
  • Security score
  • Guided remediation engine
  • Opt‑in telemetry
• Phase 8 – Dashboard & real‑time visualisation
• Phase 9 – Intelligence network & community rules marketplace

---

📬 Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• LinkedIn: 0xSemantic
• Medium: @0xSemantic
• Twitter: @0xSemantic

Happy auditing, and may your contracts be bug‑free! 🦅