Mimic is an advanced, high-precision physical cryptography and keyway analysis framework. Developed for physical security researchers, penetration testers, and locksmiths, Mimic translates the physical bitting depths of a key into mathematically flawless digital geometry.
- System Overview
- Core Capabilities
- Architecture & Stack
- Installation & Deployment
- Operational Walkthrough
- Legal & Ethics
Through optical decoding and sub-pixel calibration, Mimic enables the reverse engineering of physical keys from standard photographs. The extracted cryptographic parameters (bittings) are processed by a custom mathematical geometry engine that dynamically reconstructs standard, round, and hexagonal (Schlage) key profiles.
The finalized geometry is seamlessly exported into OpenSCAD (.SCAD) or STL formats for direct physical replication via CNC milling or high-resolution 3D printing.
| Capability | Description |
|---|---|
| Optical Keyway Decoding | Import photographs of physical keys and utilize an interactive calibration grid. Achieves ±0.05 px calibration accuracy when aligning the key shoulder and extracting physical depths. |
| Mathematical Engine | A highly specialized SVG rendering engine that calculates true V-cut boolean intersections, dynamic blade scaling, and geometrically correct tip taper angles. Maintains a geometry deviation of < 0.05 mm against physical lock specifications. |
| Parametric 3D Modeling | Translates optical bitting arrays into programmable solid 3D geometry. Generates procedural OpenSCAD scripts for physical manufacturing. Tested Profiles: Standard (Kwikset), Schlage (Hex), Yale (Round). |
| Distortion Compensation | Advanced horizontal and vertical free-axis pin nudging capabilities to compensate for perspective distortions and lens aberrations in imported reference photographs. |
The framework is constructed on a modern, highly performant web stack, ensuring zero latency during rendering and calculation.
- Core Engine: Next.js 15 (App Router)
- Language: Strict TypeScript
- State Management: Zustand (Immutable state stores for calibration coordinates)
- UI & Visualization: React-based procedural SVG generation
- Progressive Web App (PWA): Fully functional in offline, air-gapped environments via
next-pwa.
Mimic is built for high-security environments and can be run locally or completely isolated inside a Docker container.
Option A: Local Development Environment
- Clone the repository to your local machine:
git clone https://github.com/egnake/Mimic.git cd Mimic - Install dependencies via npm:
npm install
- Initialize the Next.js development server:
npm run dev
- Access the framework locally by navigating to
http://localhost:3000in your web browser.
Option B: Docker Containerization (Standalone Mode)
For penetration testing environments or isolated deployment, Mimic includes a multi-stage Docker configuration utilizing Next.js standalone mode.
- Build the lightweight production container:
docker build -t mimic-framework . - Run the container:
docker run -p 3000:3000 mimic-framework
- Access at
http://localhost:3000.
Start by selecting your target key profile (e.g., Standard Edge, Hexagonal Schlage). The Bitting Editor allows you to directly input known depths or initialize an optical decoding process.
Upload a top-down, well-lit photograph of the target key. Use the schematic overlay parameters (Zoom, X/Y Offset, Rotation, and Opacity) to perfectly align the physical key beneath the digital decoding grid.
Align the primary red axis (SHOULDER) precisely with the mechanical shoulder stop of the physical key. Use the individual pin spacing sliders to align the blue intersection nodes with the lowest points of the physical V-cuts.
Once decoded, evaluate the live SVG preview. Export the generated .SCAD file and process it through OpenSCAD to render a solid, printable .STL. The resulting geometry can be sent directly to 3D printers or CNC machines for physical bypass testing.
Warning
Academic & Authorized Use Only Mimic is developed strictly for academic research, authorized penetration testing, and legitimate physical security auditing. The developers assume no liability and are not responsible for any misuse or damage caused by this software. Use responsibly and only on hardware you own or have explicit authorization to audit.