Impacket

Impacket is a collection of Python classes providing low-level programmatic access to network protocols. It allows for constructing packets from scratch or parsing them from raw data using an object-oriented API.

Key protocol features include:

• Network Layers: Ethernet, Linux "Cooked" capture, IP (IPv4/IPv6), TCP, UDP, ICMP, IGMP, ARP.
• SMB/NMB: NMB, SMB1, SMB2, and SMB3 (high-level implementations).
• MSRPC: Version 5 support over TCP, SMB/TCP, SMB/NetBIOS, and HTTP. Includes interfaces such as EPM, DTYPES, LSAD, LSAT, NRPC, RRP, SAMR, SRVS, WKST, SCMR, BKRP, DHCPM, EVEN6, MGMT, SASEC, TSCH, DCOM, WMI, OXABREF, NSPI, and OXNSPI.
• Authentication: Plain, NTLM, and Kerberos (using passwords, hashes, tickets, or keys).
• Other: Portions of TDS (MSSQL) and LDAP implementations.

Remote test cases expect a Windows Server 2012 R2 Domain Controller. Follow these steps on the target server:

1. Disable Firewall: Set-NetFirewallProfile -Profile Domain, Public, Private -Enabled False
2. Install AD DS: Install-WindowsFeature -name AD-Domain-Services -IncludeManagementTools
3. Set Admin Password: Ensure the Administrator password meets complexity requirements.
4. Promote to DC: Use Install-ADDSForest to configure your domain.
5. Install DHCP: Install-WindowsFeature -name DHCP -IncludeManagementTools Authorize the server using netsh dhcp add securitygroups and Add-DhcpServerInDC.
6. Enable RemoteRegistry: Start-Service RemoteRegistry
7. Create a Test Admin User: Create a user with administrative rights, enable AES Kerberos encryption (RC4,AES128,AES256), and add them to the Domain Admins group.

To run tests in a fresh environment or across multiple Python versions defined in the project configuration, use tox. You can pass pytest arguments through tox using the -- separator.

To run all local tests across all configured Python versions:

tox -- -m "not remote"

To run LDAPS test cases, the Domain Controller must have a certificate installed. You can use self-signed certificates by following these steps:

1. Generate CA: Create a CA private key and public certificate using openssl.
2. Import CA: Import the CA public certificate into the Domain Controller's Cert:\LocalMachine\Root store.
3. Create Request: Create a request.inf file specifying the DC's FQDN and ProviderName = "Microsoft RSA SChannel Cryptographic Provider", then run certreq -new request.inf ldapcert.csr.
4. Sign Certificate: Use openssl x509 with a v3ext.txt file (containing extendedKeyUsage=serverAuth) to sign the CSR.
5. Install & Restart: Import the signed certificate using certreq -accept ldapcert.crt and restart the Domain Controller.

You can build and run Impacket using Docker.

To build the image:

docker build -t "impacket:latest" .

To run the image interactively:

docker run -it --rm "impacket:latest"

Impacket uses pytest to organize and run tests. Tests are categorized into local (offline) and remote (requiring an AD environment).

Running Local Tests

To run only the tests that do not require a remote target:

pytest -m "not remote"

Running Remote Tests

To run tests that require an Active Directory environment:

pytest -m "remote"

Selecting Specific Tests

You can use pytest markers or keyword expressions to filter tests. For example, to run only LDAP-related tests:

pytest -k "ldap"

To use unreleased changes from the master branch, download the development version, extract the package, and run the following command from the directory where Impacket has been unpacked:

python3 -m pipx install .

To install the latest stable release of Impacket, it is recommended to use pipx instead of pip for system-wide installations. Run the following command:

python3 -m pipx install impacket

To run the full suite of Impacket test cases, you must prepare both your local machine and a remote target environment.

1. Local Setup

Install the necessary testing dependencies using pip:

python3 -m pip install tox -r requirements-test.txt

2. Remote Setup

Remote tests require a target Active Directory environment. You must:

1. Install and configure a target Active Directory Domain Controller.
2. Configure remote test cases.

Warning: Some remote tests are not idempotent and perform changes (like creating/deleting users) on the target environment. It is highly recommended to use snapshots of the target environment so you can roll back after testing.

Mimilib test cases require the Mimikatz service to be installed on the target Domain Controller. Run Mimikatz with an elevated user and execute:

mimikatz # rpc::server

You can measure code coverage using the pytest-cov plugin.

To run tests and generate coverage using the configuration from tox.ini:

pytest --cov --cov-config=tox.ini

When using tox, it will collect and combine coverage statistics across different Python version runs. The resulting HTML report is located at htlmcov/index.html by default.