feat: Add --exclude and --skip-self options for host exclusion

[bdrogja]

feat: Add --exclude and --skip-self options for host exclusion

• Add --exclude flag to exclude specific hosts, IPs, or CIDRs from scans
• Add --skip-self flag to automatically exclude the local host
• Support for single IPs, IP ranges (x.x.x.x-y.y.y.y), and CIDR notation
• Add helper functions for IP detection and exclusion parsing

Fixes #674

Description

This PR implements host exclusion functionality for NetExec to address the issue where scanning networks that include the attacker's host or sensitive infrastructure can cause problems.

Its very important to consider, that professionell pentests are always conducted in an defined scope, therefore its necessary to be able, to exclude specific hosts to fulfill the scope.

The implementation adds two new command-line options:

• --exclude: Allows users to specify hosts, IP addresses, IP ranges, or CIDR blocks to exclude from scans
• --skip-self: Automatically detects and excludes the local host's IP address from scans

No additional dependencies are required for this change. The implementation uses Python's built-in socket and existing ipaddress libraries.

Type of change

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] This change requires a documentation update
• [ ] This requires a third party update (such as Impacket, Dploot, lsassy, etc)

Setup guide for the review

Testing Environment

• Python Version: 3.11
• OS: Tested on Docker container (python:3.11-slim)
• NetExec Version: 1.4.0 (main branch)

Testing the new features:

1. Test --exclude with single IP:

   netexec smb 192.168.1.0/24 --exclude 192.168.1.100 -u testuser -p testpass
   

   Expected: IP 192.168.1.100 should not be scanned

2. Test --exclude with multiple exclusions:

   netexec smb 10.0.0.0/16 --exclude 10.0.1.1 10.0.2.0/24 10.0.3.1-10.0.3.10 -u testuser -p testpass
   

   Expected: Excludes single IP (10.0.1.1), entire subnet (10.0.2.0/24), and IP range (10.0.3.1-10.0.3.10)

3. Test --skip-self:

   netexec smb 192.168.1.0/24 --skip-self -u testuser -p testpass --verbose
   

   Expected: Should detect local IP and exclude it (visible in verbose output)

4. Test combined usage:

   netexec smb 172.16.0.0/12 --exclude 172.16.1.0/24 --skip-self -u testuser -p testpass
   

   Expected: Excludes both specified subnet and local host

Verification with verbose mode:

Add --verbose to see exclusion details:

[*] Local IP detected: 192.168.1.50
[*] Processing exclusions: ['192.168.1.100', '192.168.1.200']
[*] Excluded 3 hosts from scan

Screenshots (if appropriate):

New help output:

Generic:
  Generic options for nxc across protocols

  --version             Display nxc version
  -t THREADS, --threads THREADS
                        set how many concurrent threads to use
  --timeout TIMEOUT     max timeout in seconds of each thread
  --jitter INTERVAL     sets a random delay between each authentication
  --exclude HOST [HOST ...]
                        exclude host(s), IP(s), CIDR(s) from the scan
  --skip-self           automatically exclude the local host from the scan

Example verbose output showing exclusion working:

[*] Local IP detected: 192.168.1.15
[*] Processing exclusions: ['192.168.1.1', '192.168.1.10-192.168.1.20']
[*] Excluded 12 hosts from scan

Checklist:

• [x] I have ran Ruff against my changes (via poetry: poetry run python -m ruff check . --preview, use --fix to automatically fix what it can)
• [x] I have added or updated the tests/e2e_commands.txt file if necessary
• [x] New and existing e2e tests pass locally with my changes
• [ ] If reliant on changes of third party dependencies, such as Impacket, dploot, lsassy, etc, I have linked the relevant PRs in those projects
• [x] I have performed a self-review of my own code
• [x] 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]

Hi thanks for the PR! Can you convert the flags into config options? I think it would be better to have these as permanent settings, so you don't need to specify them on every run

[bdrogja]

@NeffIsBack good idea. CLI Arguments + Config Options, to have more flexibility or config options only?

[NeffIsBack]

@NeffIsBack good idea.

CLI Arguments + Config Options, to have more flexibility or config options only?

Honestly I would leave it at that. When you would like to leave out a range while specifying a command you could already take care of that by not specifying it as an arg. We also have a ton of args already, so less that are added the better. Imo it fits best as a config setting

[bdrogja]

@NeffIsBack thats fine, alright. I will commit later on today ;)

[bdrogja]

Please check, test file included :)

[NeffIsBack]

@bdrogja if you got the time it would be nice if you could add a page explaining the config and how to set it up: https://github.com/Pennyw0rth/NetExec-Wiki/blob/main/getting-started/

While we are at it, we should probably create a subfolder the config file and put the other config options in getting-started in there as well

[bdrogja]

@bdrogja if you got the time it would be nice if you could add a page explaining the config and how to set it up: https://github.com/Pennyw0rth/NetExec-Wiki/blob/main/getting-started/

While we are at it, we should probably create a subfolder the config file and put the other config options in getting-started in there as well

Sure, I can take care of this and open a new PR linked to this in the other Repo. Thanks for reviewing and the good changes!

[NeffIsBack]

Would like to merge this one some time soon. The reason i haven't fully reviewed yet is that i have to test ipv6 first so that is supported as well. @bdrogja did you implement&test ipv6? Currently it looks like only IPv4 is supported