{"id":35117260,"url":"https://github.com/voltcyclone/pcileechfwgenerator","last_synced_at":"2026-05-30T02:00:46.062Z","repository":{"id":296789610,"uuid":"994386315","full_name":"VoltCyclone/PCILeechFWGenerator","owner":"VoltCyclone","description":"Automatically generates custom pcileech firmware locally from real pcie devices","archived":false,"fork":false,"pushed_at":"2026-05-29T04:05:35.000Z","size":5507,"stargazers_count":260,"open_issues_count":14,"forks_count":75,"subscribers_count":8,"default_branch":"main","last_synced_at":"2026-05-29T06:07:34.715Z","etag":null,"topics":["dma","pcie","pcileech","pcileech-fpga","pcileech-stealth","security"],"latest_commit_sha":null,"homepage":"https://pcileechfwgenerator.voltcyclone.info","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VoltCyclone.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-01T20:32:11.000Z","updated_at":"2026-05-29T04:05:22.000Z","dependencies_parsed_at":"2025-12-03T09:01:56.444Z","dependency_job_id":null,"html_url":"https://github.com/VoltCyclone/PCILeechFWGenerator","commit_stats":null,"previous_names":["ramseymcgrath/pcileechfwgenerator","voltcyclone/pcileechfwgenerator"],"tags_count":245,"template":false,"template_full_name":null,"purl":"pkg:github/VoltCyclone/PCILeechFWGenerator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VoltCyclone%2FPCILeechFWGenerator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VoltCyclone%2FPCILeechFWGenerator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VoltCyclone%2FPCILeechFWGenerator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VoltCyclone%2FPCILeechFWGenerator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VoltCyclone","download_url":"https://codeload.github.com/VoltCyclone/PCILeechFWGenerator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VoltCyclone%2FPCILeechFWGenerator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33677261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"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":["dma","pcie","pcileech","pcileech-fpga","pcileech-stealth","security"],"created_at":"2025-12-27T21:10:50.466Z","updated_at":"2026-05-30T02:00:46.056Z","avatar_url":"https://github.com/VoltCyclone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PCILeech Firmware Generator\n\n## CI/CD Status\n\n[![CI](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/consolidated-ci.yml/badge.svg?branch=main)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/consolidated-ci.yml)\n[![Security](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/security.yml)\n[![E2E](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/e2e-testing.yml/badge.svg?branch=main)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/e2e-testing.yml)\n[![Release](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/release.yml/badge.svg)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/release.yml)\n\n## Quality Metrics\n\n[![codecov](https://codecov.io/gh/voltcyclone/PCILeechFWGenerator/graph/badge.svg?token=JVX3C1WL86)](https://codecov.io/gh/voltcyclone/PCILeechFWGenerator)\n[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/voltcyclone/PCILeechFWGenerator)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE.txt)\n[![Latest Release](https://img.shields.io/github/v/release/voltcyclone/PCILeechFWGenerator?include_prereleases)](https://github.com/voltcyclone/PCILeechFWGenerator/releases)\n[![Downloads](https://img.shields.io/github/downloads/voltcyclone/PCILeechFWGenerator/total)](https://github.com/voltcyclone/PCILeechFWGenerator/releases)\n\n## Build Artifacts\n\n[![Package Build](https://img.shields.io/badge/packages-available-brightgreen)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/consolidated-ci.yml)\n[![Wheel](https://img.shields.io/badge/wheel-✓-green)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/consolidated-ci.yml)\n[![Source Distribution](https://img.shields.io/badge/sdist-✓-green)](https://github.com/voltcyclone/PCILeechFWGenerator/actions/workflows/consolidated-ci.yml)\n\n[![Discord](https://img.shields.io/badge/Discord-Support-5865F2?logo=discord\u0026logoColor=white)](https://discord.gg/dwQfMNsb7W)\n\nGenerate authentic PCIe DMA firmware from real donor hardware using a **3-stage host-container-host pipeline**. This tool extracts donor configurations from a local device via VFIO and generates unique PCILeech FPGA bitstreams.\n\n\u003e [!WARNING]\n\u003e This tool requires *real* hardware. The templates are built using the device identifiers directly from a donor card and placeholder values are explicitly avoided. Using your own donor device ensures your firmware will be unique.\n\n## Build Pipeline\n\nThe generator uses a 3-stage pipeline:\n\n1. **Stage 1 (Host)**: Collects PCIe device data via VFIO on the host\n2. **Stage 2 (Container or Local)**: Generates firmware artifacts from collected data (no VFIO access in container)\n3. **Stage 3 (Host)**: Runs Vivado synthesis on the host (optional)\n\nThe container does **NOT** access VFIO devices - it only performs templating using pre-collected data. See [Host-Container Pipeline](https://pcileechfwgenerator.voltcyclone.info/host-container-pipeline) for details.\n\n## Key Features\n\n- **Donor Hardware Analysis**: Extract real PCIe device configurations and register maps from live hardware via VFIO\n- **Overlay-Only Architecture**: Generate device-specific `.coe` configuration files that integrate with upstream `pcileech-fpga` HDL modules\n- **Dynamic Device Capabilities**: Generate realistic network, storage, media, and USB controller capabilities with pattern-based analysis\n- **Full 4KB Config-Space Shadow**: Complete configuration space emulation with BRAM-based overlay memory\n- **MSI-X Table Replication**: Exact replication of MSI-X tables from donor devices with interrupt delivery logic\n- **Unified Context Building**: Centralized template context generation ensuring consistency across all output files\n- **Active Device Interrupts**: MSI-X interrupt controller with timer-based and event-driven interrupt generation\n- **Interactive TUI**: Modern Textual-based interface with real-time device monitoring and guided workflows\n- **Containerized Build Pipeline**: Podman-based synthesis environment with automated VFIO setup\n- **USB-JTAG Flashing**: Direct firmware deployment to DMA boards via integrated flash utilities\n\n **[Complete Documentation](https://pcileechfwgenerator.voltcyclone.info)** |  **[Host-Container Pipeline](https://pcileechfwgenerator.voltcyclone.info/host-container-pipeline)** |  **[Template Architecture](https://pcileechfwgenerator.voltcyclone.info/template-architecture)** |  **[Troubleshooting Guide](https://pcileechfwgenerator.voltcyclone.info/troubleshooting)** |  **[Device Cloning Guide](https://pcileechfwgenerator.voltcyclone.info/device-cloning)** | **[Dynamic Capabilities](https://pcileechfwgenerator.voltcyclone.info/dynamic-device-capabilities)** |  **[Development Setup](https://pcileechfwgenerator.voltcyclone.info/development)**\n\n## Quick Start\n\n### Installation (Ubuntu 22.04+ / Debian 12+)\n\nModern Linux requires a virtual environment:\n\n```bash\n# Create and activate virtual environment\npython3 -m venv ~/.pcileech-venv\nsource ~/.pcileech-venv/bin/activate\n\n# Install with TUI support\npip install pcileechfwgenerator[tui]\n\n# Verify installation\npcileech version\n```\n\n\u003e ⚠️ **Don't skip the venv!** Running `pip install pcileechfwgenerator` directly will fail with `externally-managed-environment` on modern systems.\n\n### Running with Root Access (Required for VFIO)\n\nVFIO requires root. Use the venv's Python directly with sudo:\n\n```bash\n# Add this alias to ~/.bashrc for convenience:\necho \"alias pcileech-sudo='sudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main'\" \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n\n# Load VFIO modules\nsudo modprobe vfio vfio-pci\n\n# Now run commands with pcileech-sudo:\npcileech-sudo tui                                                    # Interactive TUI\npcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1   # CLI build\npcileech-sudo check --device 0000:03:00.0                            # VFIO diagnostics\n```\n\nFor complete setup including IOMMU configuration, see the **[Installation Guide](https://pcileechfwgenerator.voltcyclone.info/installation)**.\n\n### Requirements\n\n- **Python ≥ 3.11**\n- **Donor PCIe card** (any inexpensive NIC, sound, or capture card)\n- **Linux OS** with VFIO support (required for Stage 1 data collection)\n\n### Optional Requirements\n\n- **Podman** - For isolated Stage 2 templating (container does NOT access VFIO)\n- **DMA board** - pcileech_75t484_x1, pcileech_35t325_x4, or pcileech_100t484_x1\n- **Vivado** - 2022.2+ for bitstream synthesis (Stage 3)\n\n\n### CLI Commands\n\n```bash\n# Interactive TUI (recommended for first-time users)\npcileech-sudo tui\n\n# Full 3-stage build pipeline\npcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1\n\n# Stage 1 only (collect device data, no templating)\npcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1 --host-collect-only\n\n# Force local mode for Stage 2 (skip container)\npcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1 --local\n\n# Full build with Vivado synthesis (Stage 3)\npcileech-sudo build --bdf 0000:03:00.0 --board pcileech_35t325_x1 \\\n    --vivado-path /tools/Xilinx/2025.1/Vivado --vivado-jobs 8 --vivado-timeout 7200\n\n# Check VFIO configuration\npcileech-sudo check --device 0000:03:00.0\n\n# Flash firmware to device (after Vivado synthesis produces .bit file)\npcileech-sudo flash pcileech_datastore/output/*.bit --board pcileech_35t325_x1\n\n# Show version information (doesn't need sudo)\npcileech version\n```\n\n### Version Updates\n\nThe tool automatically checks for newer versions during CLI builds. You can:\n\n- Disable automatic checks: set `PCILEECH_DISABLE_UPDATE_CHECK=1`\n- Show current version: `pcileech version`\n\n\n### Development from Repository\n\n```bash\n# Clone the repository\ngit clone https://github.com/voltcyclone/PCILeechFWGenerator.git\ncd PCILeechFWGenerator\n\n# Initialize submodule (only needed for local development, NOT for container builds)\ngit submodule update --init --recursive\n\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e .\n\n# From a dev checkout you can still run the root script\nsudo -E python3 pcileech.py tui\n```\n\n\u003e **Note for developers**: When working from a git checkout for local development, you must clone with `--recurse-submodules` or run `git submodule update --init --recursive` after cloning. The `lib/voltcyclone-fpga` submodule contains FPGA board definitions and synthesis templates.\n\u003e\n\u003e **Note for container users**: The container (used only for Stage 2 templating) automatically clones the `voltcyclone-fpga` repository during image build. The container does NOT access VFIO - it only generates firmware from pre-collected device data.\n\u003e\n\u003e **Note for pip users**: The voltcyclone-fpga submodule contents are bundled automatically in pip distributions, so no additional steps are needed.\n\n## Troubleshooting\n\nHaving issues? Check our comprehensive **[Troubleshooting Guide](https://pcileechfwgenerator.voltcyclone.info/troubleshooting)** which covers:\n\n- **VFIO Setup Issues** - IOMMU configuration, module loading, device binding\n- **Installation Problems** - Virtual environment setup, Python 3.12+ issues\n- **BAR Detection Issues** - Power state problems, device compatibility  \n- **Locked IP Cores** - Vivado licensing and IP regeneration\n\n### Common Issues\n\n#### \"externally-managed-environment\" Error\n\nYou **must** use a virtual environment on modern Linux:\n\n```bash\npython3 -m venv ~/.pcileech-venv\nsource ~/.pcileech-venv/bin/activate\npip install pcileechfwgenerator[tui]\n```\n\n#### \"ModuleNotFoundError: No module named 'textual'\"\n\nInstall with TUI support:\n\n```bash\npip install pcileechfwgenerator[tui]\n```\n\n#### \"Permission denied\" / VFIO Errors\n\nUse the venv's Python with sudo:\n\n```bash\nsudo ~/.pcileech-venv/bin/python3 -m pcileechfwgenerator.pcileech_main tui\n```\n\n#### Quick Diagnostic\n\n```bash\npcileech-sudo check --device 0000:03:00.0 --interactive\n```\n\n## Direct Documentation Links\n\n- **[Installation Guide](https://pcileechfwgenerator.voltcyclone.info/installation)** - Complete installation instructions\n- **[Quick Start Guide](https://pcileechfwgenerator.voltcyclone.info/quick-start)** - Get started in minutes\n- **[Host-Container Pipeline](https://pcileechfwgenerator.voltcyclone.info/host-container-pipeline)** - Understanding the 3-stage build flow\n- **[Container Builds](https://pcileechfwgenerator.voltcyclone.info/container-builds)** - Container configuration and troubleshooting\n- **[Troubleshooting Guide](https://pcileechfwgenerator.voltcyclone.info/troubleshooting)** - Comprehensive troubleshooting and diagnostic guide\n- **[Device Cloning Process](https://pcileechfwgenerator.voltcyclone.info/device-cloning)** - Complete guide to the cloning workflow\n- **[Firmware Uniqueness](https://pcileechfwgenerator.voltcyclone.info/firmware-uniqueness)** - How authenticity is achieved\n- **[Manual Donor Dump](https://pcileechfwgenerator.voltcyclone.info/manual-donor-dump)** - Step-by-step manual extraction\n- **[PCILeech Configuration](https://pcileechfwgenerator.voltcyclone.info/pcileech-configuration)** - Key configuration parameters explained\n- **[Development Setup](https://pcileechfwgenerator.voltcyclone.info/development)** - Contributing and development guide\n- **[TUI Documentation](https://pcileechfwgenerator.voltcyclone.info/tui-readme)** - Interactive interface guide\n- **[Config space info](https://pcileechfwgenerator.voltcyclone.info/config-space-shadow)** - Config space shadow info\n\n## Output Files\n\nAfter a successful build, artifacts are placed in the datastore (default: `pcileech_datastore/`):\n\n```\npcileech_datastore/\n├── device_context.json       # Stage 1: Collected device data\n├── msix_data.json            # Stage 1: MSI-X capability data\n└── output/\n    ├── pcileech_top.sv       # Top-level SystemVerilog module\n    ├── device_config.sv      # Device configuration module\n    ├── config_space_init.hex # Configuration space initialization (BRAM)\n    ├── *.tcl                 # Vivado project/build scripts\n    └── *.bit                 # Bitstream (only after Stage 3 Vivado synthesis)\n```\n\n## Cleanup \u0026 Safety\n\n- **Rebind donors**: Use TUI/CLI to rebind donor devices to original drivers\n- **Keep firmware private**: Generated firmware contains real device identifiers\n- **Use isolated build environments**: Never build on production systems\n\n\u003e [!IMPORTANT]\n\u003e This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.\n\n## Docs\n\nDocs are managed in the [site repo](github.com/voltcyclone/pcileechfwgenerator-site) and served by cloudflare.\n\n## Acknowledgments\n\n- **PCILeech Community**: For feedback and contributions\n- @Simonrak for the writemask implementation\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.\n\n## Legal Notice\n\n*AGAIN* This tool is intended for educational research and legitimate PCIe development purposes only. Users are responsible for ensuring compliance with all applicable laws and regulations. The authors assume no liability for misuse of this software.\n\n**Security Considerations:**\n\n- Never build firmware on systems used for production or sensitive operations\n- Use isolated build environments (Seperate dedicated hardware)\n- Keep generated firmware private and secure\n- Follow responsible disclosure practices for any security research\n- Use the SECURITY.md template to raise security concerns\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltcyclone%2Fpcileechfwgenerator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoltcyclone%2Fpcileechfwgenerator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltcyclone%2Fpcileechfwgenerator/lists"}