コマンド共通アーキテクチャと依存関係

Impacket

配布とエントリーポイント

Impacket の CLI は console entry point ではなく、setup.py が examples/*.py を scripts としてインストールします。このため、コマンド名、実行権限、shebang、トップレベルの argparse 処理は各ファイル自身が所有します。ファイル名の変更は配布されるコマンド名の変更になります。

多くのコマンドは次の共通フローを持ちます。

flowchart LR
    A["argparse で入力を検証"] --> B["identity / target を分解"]
    B --> C["資格情報を選択"]
    C --> D["SMB・LDAP・RPC・Kerberos 等へ接続"]
    D --> E["コマンド固有の照会・変更"]
    E --> F["整形・ファイル出力"]
    E --> G["例外をログ化"]
    F --> H["切断・一時資源の後始末"]
    G --> H

impacket.examples.logger がログ形式を、impacket.version がバナーを、 impacket.examples.utils が domain/user[:password]@target 形式の解析や LDAP 接続などを共通化します。認証系オプションはコマンドによって差があるため、共通に見える引数を一括変更せず、各 CLI の対応プロトコルを確認してください。

プロトコル実装の詳細

コマンド横断の wire 仕様とモジュール責務はプロトコルとライブラリモジュールに分けています。

知りたいこと	ページ
`Structure` のフィールド DSL	structure.md
SMB dialect、署名、named pipe	smb.md
NTLM Type1/2/3、AV pair、MIC、SPNEGO	ntlm-spnego.md
AS/TGS、PAC、S4U、ccache	kerberos.md
string binding、NDR、RPC interface	dcerpc.md
LDAP bind、CBT、security descriptor	ldap.md
boot key、SAM/LSA/NTDS、DPAPI	dpapi-secrets.md
TDS / MQTT / NSPI	tds-messaging.md
ImpactPacket、hive、ESE、NTFS	packets-storage.md

依存レイヤー

レイヤー	主なモジュール	責務
CLI	`examples/*.py`	引数、操作選択、結果表示、終了コード
CLI 共有	`impacket.examples.*`	target 解析、シェル、secretsdump、relay、サービス配置
高水準プロトコル	`smbconnection`, `ldap.ldap`, `tds`, `dcerpc.v5.transport`	セッション、認証、transport
プロトコル構造	`smb`, `ntlm`, `krb5.`, `dcerpc.v5.*`, `dpapi`, `ese`	wire 構造、暗号処理、RPC interface
外部パッケージ	下表	ASN.1、暗号、LDAP、Web UI、文字コードなど
OS / ネットワーク	socket、raw socket、pcap、対象サービス	実際の I/O

Python パッケージ依存

setup.py と requirements.txt が宣言する実行時依存は次のとおりです。

パッケージ	主な利用箇所
`six`	Python 互換ヘルパー、byte/string 変換
`charset_normalizer`	GPP XML の文字コード判定
`pyasn1`, `pyasn1_modules`	Kerberos、CMS、LDAP ASN.1
`pycryptodomex` (`Cryptodome`)	AES、RC4/MD4、HMAC、RSA
`pyOpenSSL` (`OpenSSL`)	TLS、LDAP/MSSQL の接続検査
`ldap3`	LDAP の変更操作と security descriptor control
`ldapdomaindump`	LDAP 属性・SID の書式化補助
`flask`	`ntlmrelayx` の SOCKS/HTTP API 周辺
`pyreadline3`	Windows 上の対話シェル

追加で、sniff.py と split.py は pcapy を直接 import しますが、 setup.py / requirements.txt には宣言されていません。また CheckLDAPStatus.py と GetADComputers.py は dns.resolver を使用しますが、 dnspython は直接依存として宣言されていません。これらは開発・実行環境で別途必要になる可能性があり、依存整理を行う場合は後方互換性と各 OS でのビルド可否を確認してください。

kintercept.py は標準ライブラリの asyncore を直接使用します。 asyncore は Python 3.12 で削除されているため、project が掲げる Python 3.12/3.13 では現在のまま import できません。保守する場合は event loop の置換または互換 package の明示的な採用と、partial I/O の回帰試験が必要です。

認証と接続先の決定

代表的な入力形式は [domain/]user[:password]@target です。パスワードを省略し、-no-pass を指定しない場合は対話入力になるコマンドがあります。 NTLM の LMHASH:NTHASH、Kerberos の -k、AES key、keytab の対応はコマンドごとに異なります。

target は名前解決・SPN 構築に使われる論理名です。
-target-ip は通信先 IP を上書きし、名前解決と接続先を分離します。
-dc-ip は KDC または Domain Controller の接続先です。
Kerberos では SPN と DNS 名の整合性が重要で、IP への置換だけでは認証できない場合があります。
RPC コマンドは DCERPCTransportFactory で string binding を生成し、 SMB named pipe、TCP、RPC over HTTP などへ分岐します。
dce.set_credentials() は auth level を CONNECT まで上げます。 DRSUAPI など PKT_PRIVACY が必要な interface は明示してください。
LDAP 変更系 (dacledit / rbcd / owneredit) は ldap3、列挙系は impacket.ldap.LDAPConnection です。impacket.acl はファイル ACL です。

エラー処理と後始末

CLI の多くはプロトコル固有例外を捕捉してログへ出力します。変更時は SessionError、DCERPCException、LDAPSessionError、 KerberosError を無差別に一般例外へ畳み込まず、診断に必要な status code を保持してください。

リモートサービス、一時ファイル、共有、WMI オブジェクト、ローカル一時ファイルを作るコマンドでは、成功時だけでなく例外時の cleanup() / finish() / disconnect() も契約の一部です。新しい return や例外経路を追加するときは、必ず後始末を通ることを確認します。

コマンドを変更・追加する場合

既存 CLI の positional 引数と認証オプションを維持する。
CLI では入力と処理の流れを扱い、再利用可能な通信処理は impacket/ 側へ置く。
対象 protocol の既存 transport/session class を利用し、独自 socket 実装は protocol 実験など必要な場合に限定する。
読み取りと変更操作を明確に分け、変更操作は対象と action をログに残す。
出力形式を変える場合は、パイプ処理やツール連携への互換性を確認する。
unit test は構造体・変換・分岐を tests/ で、実環境依存の接続確認は TESTING.md の remote test 方針に従う。
新しい examples/*.py は自動的に配布対象になるため、意図しない補助スクリプトを直下へ置かない。

応答やファイルから値を取り出すときは、欠落した項目や未知の値も考慮します。また、デバッグログにパスワード、ハッシュ、チケット、鍵、復号済みの秘密情報を追加しないようにします。これらはコマンドを問わず共通の確認事項です。

検証の目安

構文: python -m compileall examples impacket
CLI: 変更したコマンドの -h と、不正入力時の終了動作
unit test: 変更した protocol/module に近い tests/ のテスト
remote test: 資格情報、対象 OS、サービス状態を固定した隔離環境
packaging: wheel を作成し、期待したスクリプトだけが含まれること

ネットワーク越しの統合試験は対象側へ状態変更を起こし得ます。特にサービス、レジストリ、LDAP security descriptor、WMI 永続化を扱う試験では、作成物とロールバック手順を先に定義してください。