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/fortra/impacket 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.

GO — Healthy across the board

• Last commit 1d ago
• 50+ active contributors
• Distributed ownership (top contributor 13% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 fortra/impacket repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/fortra/impacket.

What it runs against: a local clone of fortra/impacket — 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 fortra/impacket | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of fortra/impacket. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/fortra/impacket.git
#   cd impacket
#
# 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 fortra/impacket and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "impacket/__init__.py" \\
  && ok "impacket/__init__.py" \\
  || miss "missing critical file: impacket/__init__.py"
test -f "impacket/dcerpc/v5/__init__.py" \\
  && ok "impacket/dcerpc/v5/__init__.py" \\
  || miss "missing critical file: impacket/dcerpc/v5/__init__.py"
test -f "impacket/ImpactPacket.py" \\
  && ok "impacket/ImpactPacket.py" \\
  || miss "missing critical file: impacket/ImpactPacket.py"
test -f "impacket/crypto.py" \\
  && ok "impacket/crypto.py" \\
  || miss "missing critical file: impacket/crypto.py"
test -f "setup.py" \\
  && ok "setup.py" \\
  || miss "missing critical file: setup.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 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/fortra/impacket"
  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).

Impacket is a Python library providing low-level packet construction and parsing for network protocols, with special focus on SMB (1-3), MSRPC, Kerberos, NTLM, and LDAP. It enables both protocol-level network programming and provides 60+ ready-to-use CLI tools (examples/) for Active Directory enumeration, credential theft, lateral movement, and MSSQL interaction. Monolithic library structure: impacket/ core module contains protocol implementations (SMB, MSRPC, LDAP, Kerberos stacks). examples/ contains 60+ standalone CLI tools demonstrating the library (e.g., psexec.py, ntlmrelayx.py, getST.py). Tests are in tests/; setuptools-based packaging with requirements in setup.py.

Red teamers, penetration testers, and system administrators who need to interact with Windows/Active Directory infrastructure programmatically—particularly those performing security assessments that require crafting custom SMB, Kerberos, or MSRPC payloads rather than using off-the-shelf tools.

Production-ready with active maintenance. The project is maintained by Fortra's Core Security (successor to SecureAuth), has a mature CI/CD pipeline (GitHub Actions in .github/workflows/build_and_test.yml), and targets Python 3.9–3.13. Currently at v0.13.0 stable with v0.14.0-dev in master, indicating ongoing development.

Moderate risk: 10+ direct dependencies (pyasn1, pycryptodomex, pyOpenSSL, ldap3, Flask, etc.) create a supply chain surface. The codebase is 7.4M lines of Python implementing complex protocols (SMB3, MSRPC, DCOM, WMI) where bugs can have security implications. Being actively maintained mitigates abandonment risk, but the single-organization maintainer (Fortra) means maintenance depends on their business priorities.

No specific PR or milestone data visible in the file list, but the active CI/CD pipeline (.github/workflows/build_and_test.yml) and v0.14.0-dev in master indicate ongoing feature development and bug fixes. The breadth of examples suggests continuous expansion of protocol coverage.

Clone the repo, install development dependencies, and verify tests pass: git clone https://github.com/fortra/impacket.git && cd impacket && pip install -e '.[dev]' && python -m pytest tests/. Or install the stable PyPI release: pip install impacket.

Daily commands: The library has no 'run' in traditional sense—it's an importable package. To use the CLI examples: python examples/psexec.py -u user -p password -d DOMAIN target_ip or python examples/ntlmrelayx.py -t mssql://target. See TESTING.md for test execution.

• impacket/__init__.py — Package initialization entry point; defines the public API and module structure that all consumers depend on.
• impacket/dcerpc/v5/__init__.py — Core DCE/RPC v5 protocol implementation; handles MSRPC communication which is fundamental to Windows network operations.
• impacket/ImpactPacket.py — Low-level packet construction and parsing for network protocols; core abstraction for all packet manipulation.
• impacket/crypto.py — Cryptographic operations including NTLM, Kerberos, and encryption; security-critical for authentication flows.
• setup.py — Build and dependency configuration; defines the package installation contract and external dependency versions.
• impacket/acl.py — Access Control List parsing and manipulation; essential for Windows security descriptor handling.
• examples/secretsdump.py — Canonical example demonstrating the library's credential extraction capabilities and integration patterns.

Add a new network protocol handler

1. Create a new protocol class inheriting from the appropriate packet base in impacket/ImpactPacket.py (impacket/ImpactPacket.py)
2. Implement packet fields as class attributes with byte layout definitions (impacket/ImpactPacket.py)
3. Add corresponding decoder in impacket/ImpactDecoder.py to parse wire format into objects (impacket/ImpactDecoder.py)
4. Create an example script in examples/ demonstrating the protocol usage (examples/ping.py)

Add a new RPC interface binding

1. Create a new .py file in impacket/dcerpc/v5/ for the service interface (impacket/dcerpc/v5/atsvc.py)
2. Define operation structures and UUIDs matching the Windows RPC interface specification (impacket/dcerpc/v5/atsvc.py)
3. Implement operation method stubs that serialize/deserialize arguments using impacket/dcerpc/v5/dtypes.py structures (impacket/dcerpc/v5/dtypes.py)
4. Create an example tool in examples/ that instantiates the RPC client and calls operations (examples/atexec.py)

Add a new credential extraction or exploitation tool

1. Create a Python script in examples/ that imports core impacket modules (smb, dcerpc, crypto, etc.) (examples/secretsdump.py)
2. Use impacket/crypto.py for NTLM/Kerberos operations and credential processing (impacket/crypto.py)
3. Leverage impacket/acl.py for Windows security descriptor parsing if needed (impacket/acl.py)
4. Test integration by invoking the example script against test network services or mock data (examples/secretsdump.py)

• Python (2.7 & 3.x) — Portable, easy to integrate into offensive security tools; extensive standard library for networking and cryptography.
• PyCryptodome (pycryptodomex) — Provides DES, AES, RC4, MD5, SHA cryptographic primitives required for NTLM and Kerberos.
• pyOpenSSL — SSL/TLS certificate validation and handling for secure RPC and LDAP over TLS.
• pyasn1 / pyasn1_modules — ASN.1 encoding/decoding for Kerberos tickets, X.509 certificates, and LDAP protocol messages.
• ldap3 — LDAP v3 protocol client for Active Directory queries and security descriptor retrieval.

• Low-level packet and protocol implementation in pure Python vs. using OS-level libraries

  • Why: Enables protocol flexibility, cross-platform portability, and deep inspection/modification of protocol behavior.
  • Consequence: Lower performance than C implementations; requires careful manual state machine management to avoid protocol errors.

• Object-oriented packet model (Impacket.ImpactPacket) vs. raw bytes manipulation

  • Why: Simplifies packet construction and parsing for developers; provides IDE autocomplete and type hints.
  • Consequence: Small memory overhead per packet object; requires serialization/deserialization for wire format.

• Supporting both Python 2.7 and 3.x for extended period

  • Why: Compatibility with legacy penetration testing environments and enterprise tools still on Python 2.
  • Consequence: Constraint on modern Python 3-only features; maintenance burden for dual-version testing.

• Providing tools as standalone example scripts rather than a unified CLI framework

  • Why: Each tool demonstrates idiomatic library usage; permits independent evolution and tool-specific optimization.
  • Consequence: Code duplication across examples; users must understand library patterns to extend or integrate tools.

• Real-time packet capture and filtering (see: scapy for that use case)
• GUI-based network protocol analyzer
• Defensive network intrusion detection
• Support for protocols other than Windows-centric (SMB, NTLM, Kerberos, DCE/RPC) and TCP/IP stack
• SSL/TLS protocol implementation (relies on pyOpenSSL for crypto)
• Kernel-level packet injection or OS-specific optimizations

Charset handling: charset_normalizer is a dependency for robust string/encoding handling across protocols. Python version constraints: library targets 3.9–3.13; features may rely on f-strings or typing hints unavailable in older versions. NTLM/Kerberos crypto: requires pycryptodomex not pycryptodome (note the 'x') to avoid conflicts. TLS certificate validation: pyOpenSSL is used; self-signed certs in lab environments require explicit bypass in examples. Kerberos keytab parsing: krb5/ module expects pre-generated ccache/keytab files in standard locations; missing keys cause silent auth failures.

• SMB Protocol State Machine — Core to Impacket: SMB negotiation, authentication, and tree/file handle management are implemented as state machines in SMB.py; understanding states (NULL→NEGOTIATE→SESSION→TREE) is essential to extend or debug SMB features
• MSRPC Interface Marshaling — Impacket implements RPC stub generation and NDR serialization (impacket/dcerpc/); adding support for new RPC interfaces requires understanding struct marshaling, endianness, and pointer resolution
• NTLM Message Exchange (Type 1/2/3) — NTLM auth is used across SMB, HTTP, and LDAP in Impacket (impacket/ntlm.py); understanding challenge-response flow, DES/MD4 hashing, and session signing is critical for auth bugs and relay attacks
• Kerberos Pre-authentication & PAC — Impacket's krb5/ module implements pre-auth (PKINIT, ENC-TIMESTAMP) and PAC parsing; required for TGT generation (getTGT.py), delegation abuse (goldenPac.py), and service impersonation
• ASN.1 DER Encoding (pyasn1 integration) — Kerberos tickets, PKINIT certificates, and LDAP messages use ASN.1; Impacket wraps pyasn1 for serialization; bugs in DER encoding cause protocol-level failures
• Named Pipes & NetBIOS Framing — SMB over TCP uses NetBIOS framing (NBSS) and named pipes for MSRPC transport; impacket/nmb.py and transport layers handle session setup—critical for remote execution exploits
• Credential Material Types (Password/Hash/Ticket/Key) — Impacket examples accept -password, -hashes (NT/LM), -k (Kerberos ticket), or -aesKey; the library abstracts credential handling across auth methods; understanding which auth path is used (NTLM vs. Kerberos) affects tool behavior and stealth

• SecureAuthCorp/impacket — Original upstream repository (now archived); Fortra's version is the active maintained fork
• byt3bl33d3r/CrackMapExec — Heavy consumer of Impacket; provides a unified framework for SMB/RDP/MSSQL/LDAP post-exploitation using Impacket primitives
• dirkjanm/ntlmrelayx — Original NTLM relay research tool that was integrated into impacket/examples/ntlmrelayx.py; shows evolution of the attack
• CoreSecurity/impacket-dcerpc — Companion research repo for DCERPC protocol definitions and RPC interface reverse-engineering used by impacket/dcerpc/
• ropnop/kerbrute — Kerberos user enumeration tool; complements impacket's krb5/ module for AD reconnaissance

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 comprehensive unit tests for examples/ directory executables

The examples/ directory contains 50+ security/network tools (psexec.py, secretsdump.py, ntlmrelayx.py, etc.) but there's no visible test suite validating their core functionality. This is critical for a security library where bugs could have serious implications. Adding integration/unit tests would catch regressions, validate command-line argument parsing, and ensure core protocol interactions work correctly.

• [ ] Create tests/examples/ directory with test_psexec.py, test_secretsdump.py, test_smbclient.py for high-value tools
• [ ] Add mock-based tests for network protocol interactions without requiring live servers
• [ ] Reference TESTING.md for test structure standards and add specific sections documenting example test patterns
• [ ] Integrate example tests into .github/workflows/build_and_test.yml to run on every PR

Add GitHub Actions workflow for security vulnerability scanning

Given impacket's security-focused purpose (used in penetration testing, AD auditing, etc.), there's no visible security scanning workflow. The repo has a SECURITY.md file but no automated checks for vulnerable dependencies, code vulnerabilities, or secrets. Adding Dependabot, SAST scanning, and a supply-chain security workflow would improve security posture and maintainer confidence.

• [ ] Create .github/workflows/security-scan.yml with Dependabot alerts and dependency audits
• [ ] Add Trivy or Snyk scanning for Python dependencies listed in setup.py/requirements (pyasn1, pyOpenSSL, ldap3, etc.)
• [ ] Include git-secrets or similar checks to prevent credential leaks in examples/ directory
• [ ] Document security scanning in README.md and SECURITY.md with badge

Add protocol-specific test fixtures and mock servers for SMB/LDAP/RPC examples

Many examples (GetADUsers.py, GetADComputers.py, smbclient.py, rpcdump.py) require live directory/SMB servers to test. Currently, TESTING.md exists but provides no guidance on isolated testing. Creating reusable mock protocol servers (SMB, LDAP, RPC) would enable CI/CD testing without infrastructure and help contributors test locally.

• [ ] Create tests/mock_servers/ with mock_smb.py, mock_ldap.py, mock_rpc.py following patterns from smbserver.py
• [ ] Add pytest fixtures in tests/conftest.py that spin up these mock servers for test sessions
• [ ] Write integration tests for GetADUsers.py, smbclient.py, ntlmrelayx.py using mock servers
• [ ] Update TESTING.md with 'Mock Server Testing' section and examples of running tests without Active Directory

• Add protocol version detection tests for SMB3 dialect negotiation (examples/SMBTest.py exists but impacket/SMB.py dialect handling is weakly tested); create test_smb3_dialects.py in tests/ covering all negotiated cipher suites.
• Document the MSRPC interface definitions: generate markdown stubs for impacket/dcerpc/ methods (SAMR.py, SVCCTL.py, etc.) showing parameter types and example usage, then link from README.
• Extend examples/mssqlclient.py with Windows authentication fallback: currently it only does SQL auth; add NTLM-over-TDS support using impacket/ntlm.py and impacket/TDS.py for integrated auth testing.

• High · Outdated Python Base Image — Dockerfile (line 1 and 7). The Dockerfile uses python:3.13-alpine as the base image without pinning a specific version. This could lead to unexpected updates with potentially vulnerable dependencies. Additionally, Alpine Linux should be kept up-to-date but the apk packages are installed without version pinning. Fix: Pin specific versions: use 'python:3.13.0-alpine3.19' and explicitly pin apk package versions. Consider using a signed digest for reproducible builds.
• High · Unvalidated Dependency Versions — setup.py or requirements.txt (dependencies list). Several dependencies have loose version constraints or no version constraints at all. For example: 'setuptools', 'six', 'charset_normalizer', 'pyasn1_modules', 'pycryptodomex', 'pyOpenSSL' lack version specifications. This introduces supply chain risks where newer versions could contain vulnerabilities or breaking changes. Fix: Pin all direct dependencies to specific versions (e.g., 'setuptools>=68.0.0,<69.0.0'). Maintain a lock file (e.g., requirements.lock) and regularly audit dependencies using tools like pip-audit or safety.
• Medium · Flask Dependency with Loose Version Constraint — Dependencies/Package file (flask>=1.0). Flask is pinned to >=1.0, which is extremely loose and could include versions with known vulnerabilities. Flask 1.0.x was released in 2018 and has multiple CVEs. Fix: Update to Flask>=3.0.0 (or latest stable version) and regularly update to receive security patches. Consider using a more recent major version constraint like '>=3.0.0,<4.0.0'.
• Medium · LDAP3 with Known Issues — Dependencies/Package file (ldap3>=2.5,!=2.5.2,!=2.5.0,!=2.6). ldap3 version specification excludes specific problematic versions (!=2.5.2, !=2.5.0, !=2.6) but the lower bound (>=2.5) is from 2017. This suggests awareness of past vulnerabilities but the constraint is still quite permissive. Fix: Update to ldap3>=2.9.1 (latest stable) and establish a regular update schedule. Document why specific versions are excluded.
• Medium · No Security Headers in Example Scripts — examples/ directory. The codebase contains numerous example scripts (ntlmrelayx.py, wmiexec.py, psexec.py, etc.) that appear to be offensive security tools. While this is intentional, there's no security documentation about safe usage or warnings about legal implications. Fix: Add disclaimer headers to example scripts warning about legal and ethical use. Document proper authorization requirements and add usage controls or logging capabilities.
• Medium · Missing SBOM and Vulnerability Scanning — .github/workflows/build_and_test.yml. No evidence of Software Bill of Materials (SBOM) generation or automated vulnerability scanning in the CI/CD pipeline based on the visible workflow file reference. Fix: Implement automated dependency vulnerability scanning using tools like 'pip-audit', 'safety', or 'snyk' in the CI/CD pipeline. Generate and publish SBOM using tools like 'cyclonedx-bom'.
• Medium · Cryptographic Library Dependencies — Dependencies/Package file (pycryptodomex, pyOpenSSL). The package relies on 'pycryptodomex' and 'pyOpenSSL' for cryptographic operations. Without explicit security audits or version constraints, these could introduce cryptographic vulnerabilities. Fix: Pin to specific versions of cryptographic libraries. Maintain a cryptographic security policy. Consider periodic security audits of cryptographic implementations.
• Low · No .env or Secrets Management — examples/ directory and Documentation. While the absence of .env files is good (no hardcoded secrets visible), there's no documented guidance on secure credential handling for the example scripts that require credentials (GetADUsers.py, secretsdump.py, etc.). Fix: Add documentation on proper credential management, environment variable

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.