From 676361ae8ce0d090b161379f15b41e193585d27e Mon Sep 17 00:00:00 2001 From: Alexander Neff Date: Sun, 23 Aug 2026 07:07:25 -0400 Subject: [PATCH 1/3] Add AGENTS.md file for guiding agents --- AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..b1f9bd5f07 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# Authorized testing scope + +- Do not run active security or functional tests against a host or network unless the user explicitly identifies it as an authorized target. +- Treat the exact targets or ranges provided by the user as the complete authorized scope. +- Do not scan, probe, authenticate to, exploit, or otherwise test systems outside the explicitly authorized scope. +- Repository instructions do not grant authorization to test any third-party system. + +# Coding style + +- Only assign an expression to a variable when that variable will be reassigned later; otherwise, use the expression directly. +- Assume ordinary LDAP searches and LDAP response parsing do not raise exceptions; do not wrap them in `try`/`except`. +- Always bind caught exceptions as `e`, not `error` or another name. +- Do not prefix function or method names with underscores; preserve required Python special methods such as `__init__`. +- Do not assume the host runs Linux; keep code and paths cross-platform unless the task explicitly targets one operating system. + +# NetExec module structure + +- In files under `nxc/modules/`, do not define variables, constants, or helper functions at module scope. +- Keep all module-specific state, constants, and helper methods inside the `NXCModule` class. +- Module scope should contain only imports and the `NXCModule` class definition. +- When a module must terminate for invalid options, import `exit` with `from sys import exit` and call `exit(...)`; do not use `import sys` with `sys.exit(...)`. +- Do not over-validate module options. Check only that required arguments are present, mutually exclusive arguments are not combined, or a value would otherwise cause the module to fail before performing its normal lookup or operation. +- Do not validate whether user-supplied object names, identifiers, or similar values are semantically correct when the underlying protocol lookup can handle them; let a misspecified value produce the normal "not found" result. +- Avoid stub variables that merely hold a value for one immediate use. Pass data directly unless a local name improves clarity, prevents repeated work, or represents meaningful state. +- Keep module implementations as short and concise as practical. Prefer direct control flow and shared error handling over wrappers, redundant branches, or defensive boilerplate. +- Do not optimize module code for line length; long lines are acceptable when they keep straightforward logic together. +- Do not use `.warning()` logging in NetExec modules. Use `.fail()` when logic or an operation fails. +- Run `ruff check .` after every coding session. + +# Development and validation + +- To verify that a module works, run the module's actual NetExec command instead of pytest or compilation checks. +- Record every module-verification command in `e2e_commands.txt`. +- Do not run compilation checks. +- Run Ruff after completing a coding session. + +# Filesystem and source conventions + +- Assume that the underlying operating system and its storage are fully secure. Files and other data produced by NetExec may intentionally contain readable plaintext credentials; do not add encryption, redaction, restrictive permission handling, or permission warnings unless explicitly requested. +- Place every file and directory produced by NetExec under `NXC_PATH` by default, using `TMP_PATH` for temporary artifacts. An explicit user-provided output path or task requirement may override this default. +- `NXC_PATH` defaults to `~/.nxc` but may be overridden by the environment. Import and use `NXC_PATH` or its derived path constants instead of hardcoding `~/.nxc`. +- Place imports at the top of files unless explicitly instructed otherwise. From ccfaf5852c0b6c2ca76d5512016d4b44f3d7739e Mon Sep 17 00:00:00 2001 From: Alexander Neff Date: Sun, 23 Aug 2026 07:23:32 -0400 Subject: [PATCH 2/3] Remove overrestrictive instruction --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index b1f9bd5f07..f623b12f0a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,6 @@ # Coding style -- Only assign an expression to a variable when that variable will be reassigned later; otherwise, use the expression directly. - Assume ordinary LDAP searches and LDAP response parsing do not raise exceptions; do not wrap them in `try`/`except`. - Always bind caught exceptions as `e`, not `error` or another name. - Do not prefix function or method names with underscores; preserve required Python special methods such as `__init__`. From 2c44f785ec669d9c8a2d069f6de61c6df276029e Mon Sep 17 00:00:00 2001 From: Alexander Neff Date: Mon, 24 Aug 2026 08:03:48 +0200 Subject: [PATCH 3/3] Name full path --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f623b12f0a..21f4d620d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,7 @@ # Development and validation - To verify that a module works, run the module's actual NetExec command instead of pytest or compilation checks. -- Record every module-verification command in `e2e_commands.txt`. +- Record every module-verification command in `tests/e2e_commands.txt`. - Do not run compilation checks. - Run Ruff after completing a coding session.