| Name | marscan JSON |
| Version |
2.1.0
JSON |
| download |
| home_page | None |
| Summary | A blazing-fast, lightweight Python port scanner for ethical hackers and red teamers. |
| upload_time | 2025-08-01 16:47:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
port-scanner
security
network
pentesting
hacking
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MarScan - A Modern TCP Port Scanner for Red Teamers
[](https://pypi.org/project/marscan/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/MarwanKhatib/MarScan)
**MarScan** is a lightweight, fast, and highly extensible TCP port scanner designed for cybersecurity professionals. It provides fine-grained control over scan behavior and packet structure, enabling red teamers and penetration testers to customize their scans to evade detection by modern firewalls and intrusion detection systems (IDS).
---
## Key Features
- **Multiple Scan Techniques:** Choose from a variety of scan types, from the reliable TCP Connect scan to stealthy FIN, NULL, and XMAS scans designed to bypass firewalls.
- **Advanced Evasion Engine:** Avoid detection with features like decoy IP addresses, randomized port scanning, and scan jitter to mimic normal network traffic.
- **Granular Packet Crafting:** Manually control packet headers, including TTL, TCP window size, and TCP options, to create custom fingerprints and impersonate legitimate applications or operating systems.
- **Evasion Profiles:** Use built-in profiles (`win10`, `linux`, `stealth`) to easily apply complex evasion settings without manual configuration.
- **Rich & Readable Output:** Enjoy a clean, color-coded terminal interface that clearly distinguishes between `open`, `closed`, and `filtered` ports.
- **Flexible Reporting:** Save scan results in multiple formats, including JSON, CSV, or plain text, for easy integration into your workflow.
---
## Installation
MarScan can be installed directly from this repository using `pip`.
```bash
git clone https://github.com/MarwanKhatib/MarScan.git
cd MarScan
pip install .
```
---
## Usage
### Command-Line Options
This table provides a complete reference for all available command-line arguments.
| Flag(s) | Description | Default |
| ----------------------------- | --------------------------------------------------------------------------- | ------------ |
| `host` | The target host to scan. (Required) | - |
| `-p`, `--ports` | Ports to scan (e.g., '80', '22,80', '1-1024'). | `1-1024` |
| `-t`, `--threads` | Number of concurrent threads. | `100` |
| `-o`, `--timeout` | Connection timeout in seconds for each probe. | `2.5` |
| `-v`, `-vv` | Enable verbose output (`-v` for info, `-vv` for debug). | Off |
| **Scan Techniques** | | |
| `-sT`, `--tcp-connect-scan` | Perform a TCP connect scan. | **Default** |
| `-sS`, `--syn-scan` | Perform a SYN stealth scan. (Requires root) | Off |
| `-sF`, `--fin-scan` | Perform a FIN scan. (Requires root) | Off |
| `-sN`, `--null-scan` | Perform a NULL scan. (Requires root) | Off |
| `-sX`, `--xmas-scan` | Perform an XMAS scan. (Requires root) | Off |
| **Reporting** | | |
| `-s`, `--save-to-file` | Path to save scan results. | - |
| `-f`, `--format` | Output format for saving results. | `txt` |
| **Evasion Techniques** | | |
| `--profile` | Use a preset evasion profile (`win10`, `linux`, `stealth`). | - |
| `--decoy-ips` | Comma-separated list of decoy IP addresses. | - |
| `--scan-delay` | Add a fixed delay (in seconds) between probes. | `0.0` |
| `--scan-jitter` | Add a random delay (up to N seconds) between probes. | `0.0` |
| `--randomize-ports` | Scan ports in a random order instead of sequentially. | Off |
| **Packet Crafting** | (For Scapy-based scans like `-sS`, `-sF`, etc.) | |
| `--ttl` | Set a custom TTL for outgoing packets. | - |
| `--tcp-window` | Set a custom TCP window size. | - |
| `--tcp-options` | Set custom TCP options (e.g., `'MSS=1460,SACK'`). | - |
### Examples
- **Basic Connect Scan:**
```bash
marscan example.com -p 1-1024
```
- **Standard Stealth (SYN) Scan of all ports:**
```bash
sudo marscan example.com -p- -sS
```
- **Firewall Evasion with a FIN Scan:**
```bash
sudo marscan example.com -p 80,443,8080 -sF
```
- **Highly Evasive Scan using a Profile:**
Mimic a Windows 10 host to be less suspicious.
```bash
sudo marscan example.com -p 1-1024 -sS --profile win10
```
- **Slow, Evasive Scan with Custom Jitter:**
Randomize ports and add up to 3 seconds of jitter to avoid behavioral detection.
```bash
sudo marscan example.com -p 1-1024 -sS --randomize-ports --scan-jitter 3
```
- **Save results to a JSON file with verbose output:**
```bash
marscan example.com -p 80,443 -o scan_results.json -f json -v
```
---
## Scanning Techniques in Depth
Each scanning technique has a unique way of determining a port's status, with different trade-offs between accuracy, stealth, and privileges.
#### 1. TCP Connect Scan (`-sT`)
- **How it Works:** This is the most straightforward scanning method. It uses the operating system's standard networking functions to attempt a full three-way TCP handshake with the target port.
- **Dependencies:** Relies entirely on the host OS. It does not craft raw packets.
- **Use Case:** The most reliable scan for determining if a port is truly open. It's an excellent choice when stealth is not a concern.
- **Privileges:** Does **not** require root privileges.
- **Results:**
- `open`: The handshake completed successfully.
- `closed`: The target actively refused the connection (`RST` packet).
- `filtered`: The connection timed out, indicating a firewall is likely present.
#### 2. TCP SYN Scan (`-sS`)
- **How it Works:** A "half-open" scan. It sends a `SYN` packet, and if it receives a `SYN-ACK` response (indicating the port is open), it immediately sends a `RST` packet to tear down the connection before the handshake is completed.
- **Dependencies:** Requires raw packet crafting via the **Scapy** library.
- **Use Case:** The classic "stealth" scan. Because the full connection is never established, it is often not logged by applications, making it much quieter.
- **Privileges:** **Requires root privileges.**
- **Results:**
- `open`: The target responded with a `SYN-ACK`.
- `closed`: The target responded with a `RST-ACK`.
- `filtered`: No response was received, indicating the packet was likely dropped.
#### 3. FIN (`-sF`), NULL (`-sN`), and XMAS (`-sX`) Scans
These are highly stealthy scans designed to bypass older, stateless firewalls by sending non-standard packets.
- **How they Work:**
- **FIN Scan (`-sF`):** Sends a packet with only the `FIN` flag.
- **NULL Scan (`-sN`):** Sends a packet with **no flags**.
- **XMAS Scan (`-sX`):** Sends a packet with the `FIN`, `PSH`, and `URG` flags.
- **Dependencies:** All three rely on **Scapy** for raw packet crafting.
- **Use Case:** Excellent for evading simple packet-filtering firewalls. A compliant system (per RFC 793) will not respond if the port is open and will send a `RST` if it's closed.
- **Privileges:** **Requires root privileges.**
- **Results:**
- `open|filtered`: No response was received. The port is either open or a stateful firewall is blocking the probe.
- `closed`: The target responded with a `RST-ACK`.
---
## Project Architecture
MarScan's architecture is designed to be modular and extensible.
- `marscan/main.py`: The main entry point and CLI argument parser.
- `marscan/scanner/`: Contains the different scan type implementations.
- `base.py`: The base class for all scanners, handling threading and progress bars.
- `stealth.py`: A common base class for stealthy scans (FIN, NULL, XMAS).
- `connect.py`, `syn.py`, etc.: The specific scanner implementations.
- `marscan/utils/`: Contains utility functions for logging, display, and port parsing.
- `marscan/reporting.py`: Handles saving scan results to different file formats.
---
## Contributing
Contributions are welcome! Please feel free to open an issue or submit a pull request.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
## Contact
- **Author**: MarwanKhatib
- **GitHub**: [https://github.com/MarwanKhatib/MarScan](https://github.com/MarwanKhatib/MarScan)
- **LinkedIn**: [https://www.linkedin.com/in/marwan-alkhatib-426010323/](https://www.linkedin.com/in/marwan-alkhatib-426010323/)
- **X**: [https://x.com/MarwanAl56ib](https://x.com/MarwanAl56ib)
Raw data
{
"_id": null,
"home_page": null,
"name": "marscan",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "port-scanner, security, network, pentesting, hacking",
"author": null,
"author_email": "Marwan ALkhatib <marwanalkhatibeh@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/42/7f/fe2ee84e2299299fb002d00e225dd81af92cb612b86b4f2492a2ed9e28bb/marscan-2.1.0.tar.gz",
"platform": null,
"description": "# MarScan - A Modern TCP Port Scanner for Red Teamers\n\n[](https://pypi.org/project/marscan/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/MarwanKhatib/MarScan)\n\n**MarScan** is a lightweight, fast, and highly extensible TCP port scanner designed for cybersecurity professionals. It provides fine-grained control over scan behavior and packet structure, enabling red teamers and penetration testers to customize their scans to evade detection by modern firewalls and intrusion detection systems (IDS).\n\n---\n\n## Key Features\n\n- **Multiple Scan Techniques:** Choose from a variety of scan types, from the reliable TCP Connect scan to stealthy FIN, NULL, and XMAS scans designed to bypass firewalls.\n- **Advanced Evasion Engine:** Avoid detection with features like decoy IP addresses, randomized port scanning, and scan jitter to mimic normal network traffic.\n- **Granular Packet Crafting:** Manually control packet headers, including TTL, TCP window size, and TCP options, to create custom fingerprints and impersonate legitimate applications or operating systems.\n- **Evasion Profiles:** Use built-in profiles (`win10`, `linux`, `stealth`) to easily apply complex evasion settings without manual configuration.\n- **Rich & Readable Output:** Enjoy a clean, color-coded terminal interface that clearly distinguishes between `open`, `closed`, and `filtered` ports.\n- **Flexible Reporting:** Save scan results in multiple formats, including JSON, CSV, or plain text, for easy integration into your workflow.\n\n---\n\n## Installation\n\nMarScan can be installed directly from this repository using `pip`.\n\n```bash\ngit clone https://github.com/MarwanKhatib/MarScan.git\ncd MarScan\npip install .\n```\n\n---\n\n## Usage\n\n### Command-Line Options\n\nThis table provides a complete reference for all available command-line arguments.\n\n| Flag(s) | Description | Default |\n| ----------------------------- | --------------------------------------------------------------------------- | ------------ |\n| `host` | The target host to scan. (Required) | - |\n| `-p`, `--ports` | Ports to scan (e.g., '80', '22,80', '1-1024'). | `1-1024` |\n| `-t`, `--threads` | Number of concurrent threads. | `100` |\n| `-o`, `--timeout` | Connection timeout in seconds for each probe. | `2.5` |\n| `-v`, `-vv` | Enable verbose output (`-v` for info, `-vv` for debug). | Off |\n| **Scan Techniques** | | |\n| `-sT`, `--tcp-connect-scan` | Perform a TCP connect scan. | **Default** |\n| `-sS`, `--syn-scan` | Perform a SYN stealth scan. (Requires root) | Off |\n| `-sF`, `--fin-scan` | Perform a FIN scan. (Requires root) | Off |\n| `-sN`, `--null-scan` | Perform a NULL scan. (Requires root) | Off |\n| `-sX`, `--xmas-scan` | Perform an XMAS scan. (Requires root) | Off |\n| **Reporting** | | |\n| `-s`, `--save-to-file` | Path to save scan results. | - |\n| `-f`, `--format` | Output format for saving results. | `txt` |\n| **Evasion Techniques** | | |\n| `--profile` | Use a preset evasion profile (`win10`, `linux`, `stealth`). | - |\n| `--decoy-ips` | Comma-separated list of decoy IP addresses. | - |\n| `--scan-delay` | Add a fixed delay (in seconds) between probes. | `0.0` |\n| `--scan-jitter` | Add a random delay (up to N seconds) between probes. | `0.0` |\n| `--randomize-ports` | Scan ports in a random order instead of sequentially. | Off |\n| **Packet Crafting** | (For Scapy-based scans like `-sS`, `-sF`, etc.) | |\n| `--ttl` | Set a custom TTL for outgoing packets. | - |\n| `--tcp-window` | Set a custom TCP window size. | - |\n| `--tcp-options` | Set custom TCP options (e.g., `'MSS=1460,SACK'`). | - |\n\n### Examples\n\n- **Basic Connect Scan:**\n ```bash\n marscan example.com -p 1-1024\n ```\n\n- **Standard Stealth (SYN) Scan of all ports:**\n ```bash\n sudo marscan example.com -p- -sS\n ```\n\n- **Firewall Evasion with a FIN Scan:**\n ```bash\n sudo marscan example.com -p 80,443,8080 -sF\n ```\n\n- **Highly Evasive Scan using a Profile:**\n Mimic a Windows 10 host to be less suspicious.\n ```bash\n sudo marscan example.com -p 1-1024 -sS --profile win10\n ```\n\n- **Slow, Evasive Scan with Custom Jitter:**\n Randomize ports and add up to 3 seconds of jitter to avoid behavioral detection.\n ```bash\n sudo marscan example.com -p 1-1024 -sS --randomize-ports --scan-jitter 3\n ```\n\n- **Save results to a JSON file with verbose output:**\n ```bash\n marscan example.com -p 80,443 -o scan_results.json -f json -v\n ```\n\n---\n\n## Scanning Techniques in Depth\n\nEach scanning technique has a unique way of determining a port's status, with different trade-offs between accuracy, stealth, and privileges.\n\n#### 1. TCP Connect Scan (`-sT`)\n- **How it Works:** This is the most straightforward scanning method. It uses the operating system's standard networking functions to attempt a full three-way TCP handshake with the target port.\n- **Dependencies:** Relies entirely on the host OS. It does not craft raw packets.\n- **Use Case:** The most reliable scan for determining if a port is truly open. It's an excellent choice when stealth is not a concern.\n- **Privileges:** Does **not** require root privileges.\n- **Results:**\n - `open`: The handshake completed successfully.\n - `closed`: The target actively refused the connection (`RST` packet).\n - `filtered`: The connection timed out, indicating a firewall is likely present.\n\n#### 2. TCP SYN Scan (`-sS`)\n- **How it Works:** A \"half-open\" scan. It sends a `SYN` packet, and if it receives a `SYN-ACK` response (indicating the port is open), it immediately sends a `RST` packet to tear down the connection before the handshake is completed.\n- **Dependencies:** Requires raw packet crafting via the **Scapy** library.\n- **Use Case:** The classic \"stealth\" scan. Because the full connection is never established, it is often not logged by applications, making it much quieter.\n- **Privileges:** **Requires root privileges.**\n- **Results:**\n - `open`: The target responded with a `SYN-ACK`.\n - `closed`: The target responded with a `RST-ACK`.\n - `filtered`: No response was received, indicating the packet was likely dropped.\n\n#### 3. FIN (`-sF`), NULL (`-sN`), and XMAS (`-sX`) Scans\nThese are highly stealthy scans designed to bypass older, stateless firewalls by sending non-standard packets.\n\n- **How they Work:**\n - **FIN Scan (`-sF`):** Sends a packet with only the `FIN` flag.\n - **NULL Scan (`-sN`):** Sends a packet with **no flags**.\n - **XMAS Scan (`-sX`):** Sends a packet with the `FIN`, `PSH`, and `URG` flags.\n- **Dependencies:** All three rely on **Scapy** for raw packet crafting.\n- **Use Case:** Excellent for evading simple packet-filtering firewalls. A compliant system (per RFC 793) will not respond if the port is open and will send a `RST` if it's closed.\n- **Privileges:** **Requires root privileges.**\n- **Results:**\n - `open|filtered`: No response was received. The port is either open or a stateful firewall is blocking the probe.\n - `closed`: The target responded with a `RST-ACK`.\n\n---\n\n## Project Architecture\n\nMarScan's architecture is designed to be modular and extensible.\n- `marscan/main.py`: The main entry point and CLI argument parser.\n- `marscan/scanner/`: Contains the different scan type implementations.\n - `base.py`: The base class for all scanners, handling threading and progress bars.\n - `stealth.py`: A common base class for stealthy scans (FIN, NULL, XMAS).\n - `connect.py`, `syn.py`, etc.: The specific scanner implementations.\n- `marscan/utils/`: Contains utility functions for logging, display, and port parsing.\n- `marscan/reporting.py`: Handles saving scan results to different file formats.\n\n---\n\n## Contributing\nContributions are welcome! Please feel free to open an issue or submit a pull request.\n\n## License\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n\n## Contact\n- **Author**: MarwanKhatib\n- **GitHub**: [https://github.com/MarwanKhatib/MarScan](https://github.com/MarwanKhatib/MarScan)\n- **LinkedIn**: [https://www.linkedin.com/in/marwan-alkhatib-426010323/](https://www.linkedin.com/in/marwan-alkhatib-426010323/)\n- **X**: [https://x.com/MarwanAl56ib](https://x.com/MarwanAl56ib)\n",
"bugtrack_url": null,
"license": null,
"summary": "A blazing-fast, lightweight Python port scanner for ethical hackers and red teamers.",
"version": "2.1.0",
"project_urls": {
"Homepage": "https://github.com/MarwanKhatib/MarScan"
},
"split_keywords": [
"port-scanner",
" security",
" network",
" pentesting",
" hacking"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a68e1f16d7ee0f897407f6ddf28179bd3d2b3188d48cbab3270f0706d7aeb38a",
"md5": "f481744b89f7f54adee7f37074f755ee",
"sha256": "053f9b4500ece734873cbdff582988f87231157e7fc4549d70203dc9b4bda517"
},
"downloads": -1,
"filename": "marscan-2.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f481744b89f7f54adee7f37074f755ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19740,
"upload_time": "2025-08-01T16:47:29",
"upload_time_iso_8601": "2025-08-01T16:47:29.946737Z",
"url": "https://files.pythonhosted.org/packages/a6/8e/1f16d7ee0f897407f6ddf28179bd3d2b3188d48cbab3270f0706d7aeb38a/marscan-2.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "427ffe2ee84e2299299fb002d00e225dd81af92cb612b86b4f2492a2ed9e28bb",
"md5": "07f689b920c01352fb06e57a4ef9369f",
"sha256": "5476b70af9b63a12fc7e6db9af9cee0b1a14fe7fdd0294f240284eab3e6793bf"
},
"downloads": -1,
"filename": "marscan-2.1.0.tar.gz",
"has_sig": false,
"md5_digest": "07f689b920c01352fb06e57a4ef9369f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19795,
"upload_time": "2025-08-01T16:47:31",
"upload_time_iso_8601": "2025-08-01T16:47:31.981981Z",
"url": "https://files.pythonhosted.org/packages/42/7f/fe2ee84e2299299fb002d00e225dd81af92cb612b86b4f2492a2ed9e28bb/marscan-2.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-01 16:47:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MarwanKhatib",
"github_project": "MarScan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "marscan"
}
