If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/AlessandroZ/LaZagne shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 8mo ago

• Last commit 8mo ago
• 11 active contributors
• LGPL-3.0 licensed
• CI configured
• ⚠ Slowing — last commit 8mo ago
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits
• ⚠ LGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live AlessandroZ/LaZagne repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/AlessandroZ/LaZagne.

What it runs against: a local clone of AlessandroZ/LaZagne — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in AlessandroZ/LaZagne | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 261 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of AlessandroZ/LaZagne. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/AlessandroZ/LaZagne.git
#   cd LaZagne
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of AlessandroZ/LaZagne and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "AlessandroZ/LaZagne(\\.git)?\\b" \\
  && ok "origin remote is AlessandroZ/LaZagne" \\
  || miss "origin remote is not AlessandroZ/LaZagne (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-3.0" \\
  || miss "license drift — was LGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Linux/laZagne.py" \\
  && ok "Linux/laZagne.py" \\
  || miss "missing critical file: Linux/laZagne.py"
test -f "Linux/lazagne/config/manage_modules.py" \\
  && ok "Linux/lazagne/config/manage_modules.py" \\
  || miss "missing critical file: Linux/lazagne/config/manage_modules.py"
test -f "Linux/lazagne/config/run.py" \\
  && ok "Linux/lazagne/config/run.py" \\
  || miss "missing critical file: Linux/lazagne/config/run.py"
test -f "Linux/lazagne/config/write_output.py" \\
  && ok "Linux/lazagne/config/write_output.py" \\
  || miss "missing critical file: Linux/lazagne/config/write_output.py"
test -f "Linux/lazagne/config/constant.py" \\
  && ok "Linux/lazagne/config/constant.py" \\
  || miss "missing critical file: Linux/lazagne/config/constant.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 261 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~231d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/AlessandroZ/LaZagne"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

LaZagne is a cross-platform (Windows/Linux/macOS) credential recovery tool that automatically extracts passwords from 100+ applications by reversing their storage mechanisms—whether plaintext, encrypted databases, APIs, or custom algorithms. It recovers credentials from browsers (Chrome, Firefox, Edge, etc.), email clients, FTP/SSH tools, VPNs, and system secrets, outputting results in JSON or plain text formats. Platform-specific monolithic architecture: Windows/, Linux/, and implied Mac/ directories each contain their own laZagne.py entry point and lazagne/ package with identical structure. Shared functionality lives in lazagne/config/ (crypto utilities in crypto/, memory scanning in lib/memorpy/, module discovery in manage_modules.py), while extraction modules are organized by category under lazagne/softwares/browsers/, softwares/ (implied for other categories). Each module inherits from a base class defined in module_info.py and registers itself via manage_modules.py.

Security professionals, penetration testers, and incident responders who need to audit password storage on compromised or client machines; also forensic analysts recovering credentials post-breach. It's used both as a standalone tool and integrated into the Pupy post-exploitation framework for in-memory execution without disk artifacts.

Actively maintained and production-ready: the project has CI/CD pipelines (GitHub Actions for Windows compilation and Python linting via .github/workflows/), structured versioning (CHANGELOG present), and a comprehensive supported software list across three OSes. Latest activity and standalone binaries are available on the releases page, indicating regular maintenance by Alessandro Z.

Moderate risk: the codebase is monolithic (1.5MB of Python, single maintainer model) with tight coupling between OS-specific modules (Windows/, Linux/, macOS/ directories) making cross-platform changes risky. Dependencies include cryptographic libraries (pycryptodome, pyaes, pbkdf2) that require careful version management; no public test suite is evident in the file listing. The tool's nature (extracting credentials from running systems) means misconfiguration can expose sensitive data or fail silently on updated software versions.

Active CI/CD setup with Windows binary compilation (.github/workflows/WinCompile.yml) and Python linting (lint_python.yml) suggests ongoing releases. The CHANGELOG exists but specific recent changes are not visible in the file list; the project maintains standalone releases separately from source, indicating mature release management rather than development-stage churn.

git clone https://github.com/AlessandroZ/LaZagne.git
cd LaZagne
pip install -r requirements.txt
python Linux/laZagne.py all

On Linux/macOS use Linux/laZagne.py; on Windows use Windows/laZagne.exe (precompiled) or build from source via the CI pipeline. Use --password flag to provide known credentials for decryption.

Daily commands: Entry points are platform-specific:

# Linux/macOS
python Linux/laZagne.py all
python Linux/laZagne.py browsers -firefox
python Linux/laZagne.py all -oJ -output /tmp/creds

# Windows (or build standalone)
laZagne.exe all
laZagne.exe all -oA -output C:\Users\test\Desktop

Use -h for full option listing, -vv for verbose output, -quiet to suppress stdout (useful with -oA output flag).

• Linux/laZagne.py — Linux platform entry point; initializes the application, loads configuration, and orchestrates module execution
• Linux/lazagne/config/manage_modules.py — Core module loader and manager; dynamically discovers and instantiates credential recovery modules across all software categories
• Linux/lazagne/config/run.py — Primary execution engine; coordinates module execution, handles errors, and manages the credential extraction workflow
• Linux/lazagne/config/write_output.py — Output formatter and writer; serializes recovered credentials to multiple formats (JSON, plaintext) and handles file I/O
• Linux/lazagne/config/constant.py — Global configuration and constants; defines paths, encryption keys, and application-wide settings used across all modules
• Linux/lazagne/config/crypto — Cryptographic utilities library; provides AES, DES, and PBKDF2 implementations essential for decrypting stored credentials
• Linux/lazagne/config/module_info.py — Module metadata and base class; defines the interface all credential recovery modules must implement

Add a new credential recovery module for a specific software

1. Create a new Python file in the appropriate category (softwares/browsers/, softwares/sysadmin/, etc.) (Linux/lazagne/softwares/browsers/new_software.py)
2. Inherit from the module base class and implement required methods (run, extract credentials) (Linux/lazagne/config/module_info.py)
3. Define the softname, paths (often from constant.py), and credential location logic (Linux/lazagne/config/constant.py)
4. Use cryptographic utilities from config/crypto/ if the software encrypts credentials (Linux/lazagne/config/crypto/pyaes/aes.py)
5. Return discovered credentials as structured dictionaries; output formatting is handled by write_output.py (Linux/lazagne/config/write_output.py)

Add support for a new platform (e.g., new Linux distribution or BSD)

1. Create a new platform directory (e.g., BSD/) mirroring the Linux/ or Mac/ structure (BSD/laZagne.py)
2. Implement platform-specific path resolution in constant.py for the new OS (BSD/lazagne/config/constant.py)
3. Subclass or fork platform-specific modules (e.g., LinProcess to BSDProcess) in config/lib/memorpy/ (BSD/lazagne/config/lib/memorpy/BSDProcess.py)
4. Create a PyInstaller .spec file for the new platform's standalone binary (BSD/lazagne.spec)
5. Reuse cross-platform modules (browsers, git, crypto) unchanged via symlink or copy (BSD/lazagne/softwares/browsers/firefox_browsers.py)

Extend credential decryption for a new cipher or key derivation algorithm

1. Add the new cipher class or KDF function to the crypto/ package (Linux/lazagne/config/crypto/new_cipher.py)
2. Import and use it in the module targeting the software that uses this cipher (Linux/lazagne/softwares/browsers/firefox_browsers.py)
3. Test decryption against sample encrypted credential files from that software (Linux/lazagne/config/crypto/__init__.py)

Add a new output format (e.g., CSV or encrypted JSON export)

1. Extend write_output.py with a new formatter class or method (Linux/lazagne/config/write_output.py)
2. Parse the new output flag in the CLI argument parser (Linux/laZagne.py)
3. Call the formatter from the main execution loop in run.py (Linux/lazagne/config/run.py)

• Python 2/3 (multi-version support) — Cross-platform compatibility for Windows, Linux, macOS; existing penetration testing ecosystem standardization
• PyInstaller (.spec files) — Compiles to standalone executables without requiring Python interpreter on target systems; essential for post-exploitation deployment
• Custom AES/DES/PBKDF2 implementations (pyaes, pyDes) — Avoids external crypto library dependencies that may be unavailable on hardened systems; enables offline decryption of industry-standard encryption
• Process memory introspection (memorpy library) — Extracts in-memory plaintext credentials from running applications; bypasses encrypted storage when passwords are temporarily decrypted
• Direct file system access (no API abstraction) — Reads configuration files, database files, and key stores directly; does not rely on application APIs which may be restricted or require authentication

• Modular software-specific extraction vs. generic parsing

  • Why: Each application encrypts/stores passwords differently (SQLite, custom binary formats, key managers); generic approach would fail on most targets
  • Consequence: Requires adding new module for each software; scales linearly with supported applications but maximizes recovery success per application

• Platform-specific directory structures (Linux/, Mac/, Windows) vs. unified codebase

  • Why: Operating systems differ in file paths, process APIs, keyring systems, and build toolchains
  • Consequence: Code duplication across platforms; easier per-platform maintenance and optimization but increased maintenance burden

• Embedded cryptography libraries vs. external dependencies

  • Why: External crypto libraries may not be pre-installed or importable on locked-down systems; embedded code ensures portability
  • Consequence: Larger binary footprint; potential for custom crypto implementation bugs; reduces external attack surface during deployment

Administrator privileges: On Windows and Linux, many modules (WiFi, DPAPI-encrypted secrets, system keyrings) silently fail without UAC/sudo—users must run as admin but this is not enforced, causing false negatives. Interactive mode (-i): Pops a GUI password prompt on macOS; can hang headless/SSH sessions without explicit fallback handling. Path assumptions: Code assumes standard install locations (e.g., ~/.config/chromium on Linux, AppData\Roaming on Windows); non-standard installations are skipped silently. Dependency version pinning: pycryptodome and pyaes versions may conflict with other tools in the same venv—see requirements.txt for exact pins. Memory scanning accuracy: The memorpy library relies on ctypes/ptrace which is OS-version-sensitive; newer Windows/Linux kernels may block access patterns without clear error messages.

• DPAPI (Data Protection API) — Windows uses DPAPI to encrypt credentials in registry and files; LaZagne must decrypt via user/machine keys, which requires understanding CryptUnprotectData syscalls and key derivation from Windows secrets
• AES-256-GCM Authenticated Encryption — Modern browsers (Chrome, Edge) encrypt login databases with AES-256-GCM using a master key derived from the OS keyring; LaZagne's pyaes and pycryptodome implementations must handle both encryption modes and tag verification
• PBKDF2 Key Derivation — Many applications (Firefox, encrypted vaults) use PBKDF2 to stretch passwords into encryption keys; LaZagne implements this in config/crypto/pbkdf2.py to decrypt stored credentials given a known master password
• SQLite Database Forensics — Browser login databases, email clients, and VPN tools store credentials in SQLite format; LaZagne must parse .db files, handle journal recovery, and extract encrypted blobs while the database is in use
• Process Memory Scanning (ptrace/ReadProcessMemory) — LaZagne's memorpy library scans running process memory without hooks; this requires OS-level syscalls (Linux ptrace, Windows ReadProcessMemory) and understanding memory layout to find unencrypted credential buffers
• Linux Keyring/SecretStorage DBus Protocol — Linux applications (GNOME, KDE) store credentials via SecretService protocol over DBus; LaZagne must interface with this service to unlock and retrieve stored secrets, unlike simple file-based Windows extraction
• macOS Keychain Access Control Lists (ACL) — macOS Keychain requires user password or interactive authentication to unlock credential items; LaZagne's -i flag prompts for this, or attempts brute-force using previously-found passwords—understanding ACL policies is critical to graceful failure handling

• n1nj4sec/pupy — Post-exploitation framework that integrates LaZagne as an in-memory module for credential harvesting on compromised systems without disk artifacts
• skelsec/pypykatz — Companion tool for NTLM/Kerberos secret extraction on Windows; LaZagne often runs alongside it to recover application passwords while pypykatz handles OS-level secrets
• KeepPassXC/keepassxc — Password manager that LaZagne targets for credential extraction; understanding KeePass database format (.kdbx) and encryption is relevant to extending LaZagne's browser/manager support
• rapid7/metasploit-framework — Penetration testing platform that includes LaZagne-derived credential dumping post-exploitation modules for Windows and Linux targets
• griffithchaffee/firepwd — Firefox password recovery tool solving the same problem as LaZagne's Firefox module; provides alternative approach to parsing and decrypting logins.json

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for cryptography modules (pbkdf2.py, pyDes.py, pyaes/)

The crypto modules in Linux/lazagne/config/crypto/ lack test coverage. These are critical security-sensitive components that decrypt stored credentials. Adding unit tests would catch regressions, ensure cross-platform compatibility, and validate correct implementation of PBKDF2, DES, and AES algorithms against known test vectors.

• [ ] Create tests/test_crypto_pbkdf2.py with test vectors from RFC 6070
• [ ] Create tests/test_crypto_pydes.py validating DES encryption/decryption
• [ ] Create tests/test_crypto_pyaes.py with NIST AES test vectors
• [ ] Add pytest configuration to root directory
• [ ] Integrate test execution into existing .github/workflows/lint_python.yml

Add CI workflow for testing on Linux (complement WinCompile.yml)

Currently .github/workflows only has WinCompile.yml and lint_python.yml. There's no Linux-specific CI to test the Linux/lazagne/ module extraction against actual Linux credential stores (secretstorage, Firefox, Chromium, etc.). This gap prevents validating Linux-specific functionality like the memorydump and secretstorage integrations.

• [ ] Create .github/workflows/LinuxTest.yml with ubuntu-latest runner
• [ ] Test Linux/lazagne/softwares/browsers/firefox_browsers.py against sample Firefox profiles
• [ ] Test Linux/lazagne/softwares/mails/thunderbird_mails.py against sample Thunderbird configs
• [ ] Mock secretstorage dependency (psutil, secretstorage) for headless testing
• [ ] Run existing lint_python.yml checks within this new workflow

Consolidate duplicate browser module code (chromium_based.py vs chromium_browsers.py)

Linux/lazagne/softwares/browsers/ contains both chromium_based.py and chromium_browsers.py. This duplication pattern also likely exists in Windows modules. Consolidating shared credential extraction logic into a single base module would reduce maintenance burden, fix inconsistencies, and make cross-platform browser support clearer.

• [ ] Audit Windows/lazagne/softwares/browsers/ for matching duplicates
• [ ] Create Linux/lazagne/softwares/browsers/base_chromium.py with shared extraction logic
• [ ] Refactor chromium_based.py and chromium_browsers.py to inherit from base_chromium.py
• [ ] Update chromium_browsers.py imports to use consolidated base class
• [ ] Add regression test validating refactored modules extract same credentials as originals

• Add unit tests for crypto module: Create tests/test_crypto.py with test vectors for config/crypto/pyaes/aes.py and config/crypto/pbkdf2.py (currently untested)—critical for verifying decryption correctness across platform updates.
• Document browser cookie/login extraction flow: Add inline docstrings to softwares/browsers/chromium_based.py::ChromiumBased.run() explaining the database schema parsing and AES-256-GCM decryption steps—current code lacks comments and is fragile to browser schema changes.
• Add graceful fallback for missing admin privileges: Wrap credential extraction calls in try-catch blocks that log which modules failed due to permissions in config/run.py, rather than silently returning empty results—users have no visibility into whether a tool didn't find creds or couldn't access them.

• Critical · Plaintext Credential Extraction Tool — Project scope - entire codebase. LaZagne is a credentials recovery tool designed to retrieve passwords from local storage. While legitimate for authorized security testing, the codebase itself extracts and may expose sensitive credentials. The tool has inherent risk of misuse for unauthorized credential theft. Fix: Implement strict access controls, audit logging, and require explicit user consent. Add warnings about legal implications. Consider implementing credential masking in output and enforcing encryption at rest for recovered credentials.
• High · Use of Deprecated Custom Cryptography — Linux/lazagne/config/crypto/pyDes.py, Linux/lazagne/config/crypto/pyaes/, Linux/lazagne/config/crypto/pbkdf2.py. The codebase includes custom implementations of cryptographic algorithms (pyDes, pyaes, pbkdf2) instead of using modern, audited libraries. Custom crypto implementations in 'Linux/lazagne/config/crypto/' are prone to implementation errors and side-channel attacks. Fix: Replace custom cryptographic implementations with well-tested libraries like cryptography.io or PyCryptodome for all operations. Remove pyDes and custom pyaes implementations. Use bcrypt or argon2 for password hashing instead of custom PBKDF2.
• High · Memory Dumping Capability — Linux/lazagne/config/lib/memorpy/ (all files), Linux/lazagne/softwares/memory/memorydump.py, Linux/lazagne/softwares/memory/mimipy.py. The memorpy library (Linux/lazagne/config/lib/memorpy/) provides process memory introspection and dumping capabilities. This can be used to extract sensitive data directly from process memory, including encryption keys and credentials in transit. Fix: Implement process privilege checks and require explicit user authorization. Add comprehensive audit logging of all memory access. Consider restricting memory dumping to specific whitelisted processes only. Add warnings about sensitive data exposure risks.
• High · Outdated Dependencies with Known Vulnerabilities — requirements.txt (dependency declarations). Dependency 'pyasn1' is known to have had security issues. The requirements.txt does not specify version pinning, allowing installation of potentially vulnerable versions. pycryptodome should be kept updated as cryptographic libraries frequently receive security patches. Fix: Pin all dependencies to specific, verified secure versions. Implement automated dependency scanning with tools like safety or Snyk. Establish a regular dependency update schedule. Remove or replace pyasn1 with actively maintained alternatives like pyasn1_modules or use standard library equivalents.
• High · Unprotected Credential Storage in Output — Linux/lazagne/config/write_output.py. The write_output.py module handles credential output without apparent encryption or sanitization. Recovered credentials could be written to plaintext files or logs, creating persistent secrets on disk. Fix: Implement mandatory encryption for all credential output. Add option to hash sensitive fields. Implement secure deletion of temporary files. Enforce strong file permissions (600) on output files. Add configuration options to redact sensitive data from logs.
• Medium · Potential SQL Injection in Database Credential Modules — Linux/lazagne/softwares/databases/sqldeveloper.py, Linux/lazagne/softwares/databases/squirrel.py, Linux/lazagne/softwares/databases/dbvis.py. Multiple database credential extraction modules (SQLDeveloper, Squirrel, DBVis) parse configuration files and may construct queries or commands. Without proper input validation, this could lead to injection vulnerabilities. Fix: Implement strict input validation and sanitization for all file parsing. Use parameterized queries and prepared statements. Avoid string concatenation for command construction. Validate file formats before parsing.
• Medium · Weak Configuration File Permissions Handling — Linux/lazagne/softwares/sysadmin/shadow.py, Linux/lazagne/softwares/sysadmin/ssh.py, Linux/lazagne/softwares/sysadmin/fstab.py. The tool reads configuration files from various applications (shadow files, SSH configs, etc.) which may contain sensitive data. The tool may not verify proper file permissions or warn users about world-readable credential stores. Fix: Implement file permission checks before reading sensitive files. Warn users if credential files have weak permissions

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.