{"id":31890398,"url":"https://github.com/jose-blockchain/ledger-threat-modelling","last_synced_at":"2026-02-16T22:03:59.586Z","repository":{"id":295803061,"uuid":"991279101","full_name":"jose-blockchain/ledger-threat-modelling","owner":"jose-blockchain","description":"Ledger Hardwallet Threat Modelling and Attack Planning","archived":false,"fork":false,"pushed_at":"2025-05-27T11:56:52.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-13T04:47:47.306Z","etag":null,"topics":["blockchain","blockchain-security-tools","ledger","ledger-wallet","security","wallet"],"latest_commit_sha":null,"homepage":"","language":"Alloy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jose-blockchain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-27T11:47:01.000Z","updated_at":"2025-06-17T09:26:55.000Z","dependencies_parsed_at":"2025-05-27T12:53:11.760Z","dependency_job_id":"6dd15d26-d1b0-4b7d-82dd-81f4ebe5f122","html_url":"https://github.com/jose-blockchain/ledger-threat-modelling","commit_stats":null,"previous_names":["jio-gl/ledger-threat-modelling","jose-blockchain/ledger-threat-modelling"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jose-blockchain/ledger-threat-modelling","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jose-blockchain%2Fledger-threat-modelling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jose-blockchain%2Fledger-threat-modelling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jose-blockchain%2Fledger-threat-modelling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jose-blockchain%2Fledger-threat-modelling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jose-blockchain","download_url":"https://codeload.github.com/jose-blockchain/ledger-threat-modelling/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jose-blockchain%2Fledger-threat-modelling/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279014107,"owners_count":26085463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","blockchain-security-tools","ledger","ledger-wallet","security","wallet"],"created_at":"2025-10-13T07:35:23.612Z","updated_at":"2025-10-13T07:35:25.087Z","avatar_url":"https://github.com/jose-blockchain.png","language":"Alloy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ledger Hardware Wallet Threat Modelling\n\nA comprehensive threat modelling framework for Ledger hardware wallets using automated planning (PDDL) and formal methods (Alloy).\n\n## 🎯 Overview\n\nThis project provides formal security models and threat analysis for Ledger hardware wallets, including:\n\n- **Attack Planning Models** (PDDL): Automated discovery of attack paths and vulnerabilities ✅ **Working**\n- **Formal Security Models** (Alloy): Mathematical specifications of device architecture and security properties ⚠️ **Work in Progress**\n- **Comprehensive Attack Scenarios**: Physical, software, supply chain, and wireless attacks\n- **Security Property Verification**: Automated checking of key confidentiality, display integrity, and device genuineness\n\n## 📁 Repository Structure\n\n```\nledger-threat-modelling/\n├── pddl/                           # PDDL planning models (WORKING)\n│   ├── domains/                    # Attack domain definitions\n│   ├── problems/                   # Specific attack scenarios\n│   └── plans/                      # Generated attack plans\n├── alloy/                          # Alloy formal models (WIP)\n│   ├── models/                     # Core security property models\n│   ├── instances/                  # Concrete attack scenarios\n│   └── analysis/                   # Analysis and verification files\n├── docs/                           # Documentation\n├── examples/                       # Example analyses and results\n├── tools/                          # Tool installation scripts\n├── requirements.txt                # Python dependencies\n├── install.sh                      # Automated setup script\n└── README.md                       # This file\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Java 8+** (for Alloy Analyzer)\n- **Python 3.8+** (for PDDL tools and scripts)\n- **Git** (for cloning the repository)\n\n### Installation\n\n1. **Clone the repository:**\n   ```bash\n   git clone https://github.com/your-username/ledger-threat-modelling.git\n   cd ledger-threat-modelling\n   ```\n\n2. **Run the automated setup:**\n   ```bash\n   chmod +x install.sh\n   ./install.sh\n   ```\n\n   This will:\n   - Download and install Alloy Analyzer\n   - Set up PDDL planners (Fast Downward, FF)\n   - Install Python dependencies\n   - Verify the installation\n\n3. **Manual setup (alternative):**\n   ```bash\n   # Create Python virtual environment\n   python3 -m venv venv\n   source venv/bin/activate  # On Windows: venv\\Scripts\\activate\n   \n   # Install Python dependencies\n   pip install -r requirements.txt\n   \n   # Download Alloy Analyzer\n   mkdir -p tools\n   wget -O tools/alloy.jar https://github.com/AlloyTools/org.alloytools.alloy/releases/download/v6.0.0/org.alloytools.alloy.dist.jar\n   ```\n\n## 🔍 Usage\n\n### PDDL Attack Planning ✅\n\n1. **Run attack planning:**\n   ```bash\n   # Using Fast Downward planner\n   python3 tools/planners/downward/fast-downward.py \\\n     pddl/domains/ledger-comprehensive.pddl \\\n     pddl/problems/ledger-nano-s.pddl \\\n     --search \"astar(lmcut())\"\n   ```\n\n2. **Analyze generated plans:**\n   ```bash\n   # Plans are saved in the current directory as sas_plan\n   cat sas_plan\n   ```\n\n3. **Available attack scenarios:**\n   - `pddl/problems/ledger-nano-s.pddl` - Nano S physical attacks\n   - `pddl/problems/ledger-nano-x.pddl` - Nano X wireless + physical attacks  \n   - `pddl/problems/ledger-stax-comprehensive.pddl` - Stax multi-vector attacks\n\n### Alloy Security Models ⚠️ (Work in Progress)\n\n1. **Open Alloy Analyzer:**\n   ```bash\n   java -jar tools/alloy.jar\n   ```\n\n2. **Load a security model:**\n   - Open `alloy/instances/ledger_security_properties.als`\n   - Execute commands to check security properties\n   - Analyze counterexamples for attack scenarios\n\n3. **Key commands in the model:**\n   ```alloy\n   // Check if key confidentiality can be violated\n   check KeyConfidentialityAssertion for 4 but 1 Device, 1 Attacker\n   \n   // Find attack scenarios\n   run SimpleSeCompromiseAttack for 4 but 1 Device, 1 Attacker\n   run SupplyChainAttack for 4 but 1 Device, 1 Attacker\n   ```\n\n   **Note**: The Alloy models are currently under development. Some assertions may not find counterexamples as expected.\n\n## 📊 Security Models\n\n### Device Types Modeled\n\n- **Nano S**: USB-only device with MCU-driven display\n- **Nano X**: Bluetooth-enabled device with SE-driven display  \n- **Stax**: NFC/Bluetooth device with touchscreen\n\n### Attack Vectors Covered\n\n#### Physical Attacks\n- Fault injection attacks on Secure Element\n- Side-channel attacks (power, EM, timing)\n- Evil maid attacks with device replacement\n- Bootloader exploitation\n\n#### Supply Chain Attacks\n- Pre-compromised devices\n- Malicious firmware installation\n- Component substitution\n\n#### Wireless Attacks\n- Bluetooth Man-in-the-Middle\n- NFC eavesdropping\n- Proximity-based attacks\n\n#### Software Attacks\n- Malicious applications\n- Host OS compromise\n- Rogue HSM servers\n\n### Security Properties Verified\n\n1. **Key Confidentiality**: Private keys cannot be extracted\n2. **Display Integrity**: Display shows authentic information\n3. **Device Genuineness**: Device authenticity can be verified\n4. **PIN Security**: PIN cannot be bypassed without physical access\n\n## 🔬 Analysis Results\n\n### PDDL Planning Results ✅\n\n1. **Working Attack Paths**: PDDL successfully generates attack sequences for:\n   - Physical access → PIN bypass → seed extraction\n   - Supply chain compromise → pre-compromised device\n   - Wireless proximity → BLE MITM → communication eavesdropping\n   - Multi-vector attacks combining physical, software, and social engineering\n\n2. **Verified Attack Scenarios**: All device types (Nano S, Nano X, Stax) have validated attack paths\n\n### Alloy Analysis Results ⚠️ (In Development)\n\n1. **Current Limitations**: \n   - Key confidentiality assertions not finding expected counterexamples\n   - Model constraints may be too restrictive for counterexample generation\n   - Under active development to resolve assertion checking issues\n\n2. **Theoretical Coverage**: Models cover SE compromise, supply chain attacks, and multi-vector scenarios\n\n## 🛠️ Development\n\n### Adding New Attack Scenarios\n\n1. **Alloy Models**: Add new predicates in `alloy/instances/attack-scenarios.als`\n2. **PDDL Models**: Create new problem files in `pddl/problems/`\n3. **Verification**: Add corresponding check commands\n\n### Running Tests\n\n```bash\n# Test Alloy model syntax\npython3 tools/test_alloy_syntax.py\n\n# Verify PDDL domain validity\npython3 tools/test_pddl_domains.py\n```\n\n## 📚 Documentation\n\n- [Alloy Model Documentation](docs/alloy-models.md)\n- [PDDL Domain Specification](docs/pddl-domains.md)\n- [Attack Scenario Catalog](docs/attack-scenarios.md)\n- [Security Analysis Results](docs/security-analysis.md)\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/new-attack-model`)\n3. Commit your changes (`git commit -am 'Add new attack model'`)\n4. Push to the branch (`git push origin feature/new-attack-model`)\n5. Create a Pull Request\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Alloy Analyzer](https://alloytools.org/) for formal specification\n- [Fast Downward](https://www.fast-downward.org/) for automated planning\n- [Ledger](https://www.ledger.com/) for hardware wallet architecture insights\n\n## 📞 Contact\n\nFor questions or collaboration opportunities, please open an issue or contact the maintainers.\n\n---\n\n**⚠️ Disclaimer**: This research is for educational and security analysis purposes only. Do not use these models to attack real devices without proper authorization. ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjose-blockchain%2Fledger-threat-modelling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjose-blockchain%2Fledger-threat-modelling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjose-blockchain%2Fledger-threat-modelling/lists"}