feat: add --shares-depth flag for subdirectory write permission checking

[sup3rDav3]

Description

Fixes #1186: Write permissions were only checked on top-level share directories, not subdirectories. A writable subdirectory (e.g. SYSVOL\scripts) would not be detected even if the user had write access to it.

Adds a new --shares-depth argument that recursively checks subdirectories for write access up to the specified depth. Default is 0 (root only) so existing behavior is completely unchanged.

This PR was developed with the assistance of Claude (Anthropic) via claude.ai. Claude assisted with the implementation approach, and ruff linting fixes. All code was reviewed and tested by the author against a live Windows Server 2022 domain controller.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Deprecation of feature or functionality
• This change requires a documentation update
• This requires a third party update (such as Impacket, Dploot, lsassy, etc)
• This PR was created with the assistance of AI (Claude via claude.ai — see description above)

Setup guide for the review

Environment:

• Kali Linux (attacker machine)
• Python 3.13
• NetExec installed via poetry in dev mode

Target:

• Windows Server 2022 domain controller
• Domain: ad.local
• Test user: lowpriv (standard domain user with READ on SYSVOL root, WRITE on SYSVOL\ad.local\scripts)

Reproduce the bug (before fix):
nxc smb TARGET -u lowpriv -p PASS --shares
Result: SYSVOL shows READ only — writable scripts folder not detected

Test the fix:
nxc smb TARGET -u lowpriv -p PASS --shares --shares-depth 2
Result: SYSVOL shows READ,WRITE (ad.local\scripts)

Other usage:
nxc smb TARGET -u USER -p PASS --shares --shares-depth 1
nxc smb TARGET -u USER -p PASS --shares write --shares-depth 2
nxc smb TARGET -u USER -p PASS --shares --no-write-check --shares-depth 2

Screenshots (if appropriate):

Checklist:

• I have ran Ruff against my changes
• I have added or updated the tests/e2e_commands.txt file if necessary
• If reliant on changes of third party dependencies, such as Impacket, dploot, lsassy, etc, I have linked the relevant PRs in those projects
• I have linked relevant sources that describes the added technique (blog posts, documentation, etc)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (PR here: https://github.com/Pennyw0rth/NetExec-Wiki)

[NeffIsBack]

All code was reviewed and tested by the author against a live Windows Server 2022 domain controller.

Either you have not reviewed the code (and changes) or I am really curious why you have introduced +1300 lines of formatting changes.

[sup3rDav3]

All code was reviewed and tested by the author against a live Windows Server 2022 domain controller.

Either you have not reviewed the code (and changes) or I am really curious why you have introduced +1300 lines of formatting changes.

I'm not quite sure what happened TBH. Got PRs semi-mixed up, IDE got squirrelley (tabs vs. spaces formatting issues). The fix was really only 20-25 new lines. Feel free to delete this mess and so I can refine my process. Thanks.

[NeffIsBack]

All code was reviewed and tested by the author against a live Windows Server 2022 domain controller.

Either you have not reviewed the code (and changes) or I am really curious why you have introduced +1300 lines of formatting changes.

I'm not quite sure what happened TBH. Got PRs semi-mixed up, IDE got squirrelley (tabs vs. spaces formatting issues). The fix was really only 20-25 new lines. Feel free to delete this mess and so I can refine my process. Thanks.

Okay, then I will close this for now. If #1138 is validated that it properly works and integrated, we should probably go for a similar solution, because this one here would result in hundreds or thousands of folders to be written.

[sup3rDav3]

All code was reviewed and tested by the author against a live Windows Server 2022 domain controller.

Either you have not reviewed the code (and changes) or I am really curious why you have introduced +1300 lines of formatting changes.

I'm not quite sure what happened TBH. Got PRs semi-mixed up, IDE got squirrelley (tabs vs. spaces formatting issues). The fix was really only 20-25 new lines. Feel free to delete this mess and so I can refine my process. Thanks.

Okay, then I will close this for now. If #1138 is validated that it properly works and integrated, we should probably go for a similar solution, because this one here would result in hundreds or thousands of folders to be written.

Fair enough, sorry for the confusion and thanks for your time. Back to #1176 👍