# Spartan
## What is this project?
Spartan is a versatile and powerful port scanner written in Python. It allows users to quickly and efficiently scan network ports. Spartan was designed so that users can easily write custom scripts to enhance the scanner's capabilities, tailoring it to their specific needs.
## Installation
### Installing from PyPI
You can install Spartan from PyPI:
```sh
pip install spartan-scan
```
### Installing from repository
You can also install Spartan directly from the repository:
1. Clone the repository from GitHub
```
git clone https://github.com/WaletLab/Spartan.git
```
2. Navigate to the project directory
```
cd Spartan
```
3. Install the package using `pip`
```
pip install .
```
## Usage
To use Spartan, simply run the following command in your terminal:
```
# spartan [OPTIONS] COMMAND [ARGS]...
```
> Spartan requires root privileges to perform certain operations. Please run it as root or use `sudo` to ensure it has the necessary permissions.
### Port scan
#### Available scan modes:
- TCP SYN scan
```
# spartan syn [ARGS]...
```
- TCP FIN scan
```
# spartan fin [ARGS]...
```
- TCP NULL scan
```
# spartan null [ARGS]...
```
- TCP XMAS scan
```
# spartan xmas [ARGS]...
```
- UDP scan
```
# spartan udp [ARGS]...
```
#### Examples
Perform a TCP SYN scan on a target host, targeting the most commonly used TCP ports by default.
```
# spartan syn --host 1.2.3.4
```
Perform a UDP scan on a target host, targeting all possible ports.
```
# spartan udp --host 1.2.3.4 --port a
```
> Please note that scanning all possible ports can be extremely time-consuming and may encounter disruptions due to firewalls and other unforeseen circumstances. Please consider these factors when initiating such extensive scans.
Perform a TCP SYN scan on a target host, targeting only first 1024 ports and setting a custom retry timeout of 2 miliseconds.
```
# spartan syn --host 1.2.3.4 --port 1:1024 --retry-timeout 2
```
Perform a TCP SYN scan on a target host and save results to .csv file.
```
# spartan syn --host 1.2.3.4 --output
```
Perform a UDP scan on a target host without displaying banner.
```
# spartan --basic udp --host 1.2.3.4
```
> Note: --basic flag goes before scan mode!
Spartan is also capable of handling domain names.
```
# spartan syn --host waletlab.com
```
For more details please refer to `--help`
```
# spartan --help
```
```
# spartan <scan mode> --help
```
### Scripts
Spartan provides the flexibility to extend its functionality through custom python scripts. Users can leverage global variables `host` and `result` within their scripts to interact with scan results and customize behavior as needed.
#### Global variables
- `host` - Represents the target host IP address
- **`result`**: Holds the scan results, which is a dictionary where the keys are port numbers (integers) and the values are `PortResult` objects.
`PortResult` attributes:
- **`port`**: Integer representing the port number.
- **`status`**: String indicating the status of the port (e.g., "OPEN", "CLOSED").
- **`detail`**: Additional details about the port status.
#### Default scripts
Spartan comes with a set of default scripts out of the box. You can easily list them using the following command:
```
# spartan scripts
```
These default scripts provide useful functionalities and examples that you can leverage directly or use as references when writing your own custom scripts.
#### Using scripts
To use a default script, simply append the `--script` flag followed by the name of the script when executing Spartan:
```
# spartan syn --host 1.2.3.4 --script ssl_info.py
```
To use your own scripts, please follow the `--script` flag with the full path to a script file:
```
# spartan syn --host 1.2.3.4 --script /path/to/your_script.py
```
## Contributing
We welcome contributions from the community! Here’s how you can help:
### Reporting Bugs
If you find a bug, please report it by opening an issue in the [Issues](https://github.com/WaletLab/Spartan/issues) section. Before reporting, please check if the bug has already been reported.
### Suggesting Enhancements
Have a feature request or enhancement idea? Please open an issue with the tag `enhancement`. Be sure to include as much detail as possible.
### Submitting Pull Requests
1. **Fork the Repository**: Click the "Fork" button at the top right of the repository page.
2. **Clone Your Fork** and create a new branch for your changes.
3. **Make Changes** and commit them with clear messages.
4. **Push to Your Fork** and open a pull request.
For detailed instructions, refer to [GitHub's guide on contributing to projects](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project).
## License
Spartan is licensed under the GPL-3.0 license. See the [LICENSE](https://github.com/WaletLab/Spartan/blob/master/Spartan/LICENSE) file for more details.
## Disclaimer
This tool is intended for **legal and ethical use only**. We do not condone or take any responsibility for any illegal activities carried out with this tool.
## Contact
For any questions or feedback, please open an issue or contact the maintainers at [kontakt\@waletlab.com](mailto:kontakt\@waletlab.com).
Raw data
{
"_id": null,
"home_page": null,
"name": "spartan-scan",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "WaletLab <kontakt@waletlab.com>",
"keywords": "port scan, port, networking, security",
"author": null,
"author_email": "WaletLab <kontakt@waletlab.com>",
"download_url": null,
"platform": null,
"description": "# Spartan\n\n## What is this project?\nSpartan is a versatile and powerful port scanner written in Python. It allows users to quickly and efficiently scan network ports. Spartan was designed so that users can easily write custom scripts to enhance the scanner's capabilities, tailoring it to their specific needs.\n## Installation\n\n### Installing from PyPI\nYou can install Spartan from PyPI:\n```sh\npip install spartan-scan\n```\n### Installing from repository\nYou can also install Spartan directly from the repository:\n1. Clone the repository from GitHub\n```\ngit clone https://github.com/WaletLab/Spartan.git\n```\n2. Navigate to the project directory\n```\ncd Spartan\n```\n3. Install the package using `pip`\n```\npip install .\n```\n\n## Usage\nTo use Spartan, simply run the following command in your terminal:\n```\n# spartan [OPTIONS] COMMAND [ARGS]...\n```\n> Spartan requires root privileges to perform certain operations. Please run it as root or use `sudo` to ensure it has the necessary permissions. \n### Port scan\n\n#### Available scan modes:\n- TCP SYN scan \n```\n# spartan syn [ARGS]...\n```\n- TCP FIN scan \n```\n# spartan fin [ARGS]...\n```\n- TCP NULL scan\n```\n# spartan null [ARGS]...\n```\n- TCP XMAS scan\n```\n# spartan xmas [ARGS]...\n```\n- UDP scan\n```\n# spartan udp [ARGS]...\n```\n#### Examples\nPerform a TCP SYN scan on a target host, targeting the most commonly used TCP ports by default.\n```\n# spartan syn --host 1.2.3.4\n```\n\nPerform a UDP scan on a target host, targeting all possible ports.\n```\n# spartan udp --host 1.2.3.4 --port a\n```\n> Please note that scanning all possible ports can be extremely time-consuming and may encounter disruptions due to firewalls and other unforeseen circumstances. Please consider these factors when initiating such extensive scans. \n\nPerform a TCP SYN scan on a target host, targeting only first 1024 ports and setting a custom retry timeout of 2 miliseconds.\n```\n# spartan syn --host 1.2.3.4 --port 1:1024 --retry-timeout 2\n```\n\nPerform a TCP SYN scan on a target host and save results to .csv file.\n```\n# spartan syn --host 1.2.3.4 --output\n```\n\nPerform a UDP scan on a target host without displaying banner.\n```\n# spartan --basic udp --host 1.2.3.4\n```\n> Note: --basic flag goes before scan mode!\n\nSpartan is also capable of handling domain names.\n```\n# spartan syn --host waletlab.com\n```\n\nFor more details please refer to `--help`\n```\n# spartan --help\n```\n```\n# spartan <scan mode> --help\n```\n### Scripts\nSpartan provides the flexibility to extend its functionality through custom python scripts. Users can leverage global variables `host` and `result` within their scripts to interact with scan results and customize behavior as needed.\n#### Global variables\n- `host` - Represents the target host IP address\n- **`result`**: Holds the scan results, which is a dictionary where the keys are port numbers (integers) and the values are `PortResult` objects. \n `PortResult` attributes:\n\t- **`port`**: Integer representing the port number.\n\t- **`status`**: String indicating the status of the port (e.g., \"OPEN\", \"CLOSED\").\n\t- **`detail`**: Additional details about the port status.\n\n#### Default scripts\nSpartan comes with a set of default scripts out of the box. You can easily list them using the following command:\n```\n# spartan scripts\n```\nThese default scripts provide useful functionalities and examples that you can leverage directly or use as references when writing your own custom scripts.\n\n#### Using scripts\nTo use a default script, simply append the `--script` flag followed by the name of the script when executing Spartan:\n```\n# spartan syn --host 1.2.3.4 --script ssl_info.py\n```\n\nTo use your own scripts, please follow the `--script` flag with the full path to a script file:\n```\n# spartan syn --host 1.2.3.4 --script /path/to/your_script.py\n```\n\n\n\n## Contributing\nWe welcome contributions from the community! Here\u2019s how you can help:\n### Reporting Bugs\nIf you find a bug, please report it by opening an issue in the [Issues](https://github.com/WaletLab/Spartan/issues) section. Before reporting, please check if the bug has already been reported.\n### Suggesting Enhancements\nHave a feature request or enhancement idea? Please open an issue with the tag `enhancement`. Be sure to include as much detail as possible.\n### Submitting Pull Requests\n\n1. **Fork the Repository**: Click the \"Fork\" button at the top right of the repository page.\n2. **Clone Your Fork** and create a new branch for your changes.\n3. **Make Changes** and commit them with clear messages.\n4. **Push to Your Fork** and open a pull request.\n\nFor detailed instructions, refer to [GitHub's guide on contributing to projects](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project).\n## License\nSpartan is licensed under the GPL-3.0 license. See the [LICENSE](https://github.com/WaletLab/Spartan/blob/master/Spartan/LICENSE) file for more details.\n\n## Disclaimer\nThis tool is intended for **legal and ethical use only**. We do not condone or take any responsibility for any illegal activities carried out with this tool.\n\n## Contact\nFor any questions or feedback, please open an issue or contact the maintainers at [kontakt\\@waletlab.com](mailto:kontakt\\@waletlab.com).\n",
"bugtrack_url": null,
"license": null,
"summary": "TCP/IP port scanner",
"version": "2.0.0",
"project_urls": {
"Issues": "https://github.com/WaletLab/Spartan/issues",
"Repository": "https://github.com/WaletLab/Spartan.git"
},
"split_keywords": [
"port scan",
" port",
" networking",
" security"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a63383672dda91352d00c3e268be840c4e5a22c3f5c6e72d0406fa0173ab5626",
"md5": "74fcc04f3a5ded40c5764e7fc8516f07",
"sha256": "22668acd47b3e69ac98a96d478c9276c5ec4b3bf496dbfe0b4149123265ebbd2"
},
"downloads": -1,
"filename": "spartan_scan-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74fcc04f3a5ded40c5764e7fc8516f07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 464699,
"upload_time": "2024-06-12T14:39:28",
"upload_time_iso_8601": "2024-06-12T14:39:28.026551Z",
"url": "https://files.pythonhosted.org/packages/a6/33/83672dda91352d00c3e268be840c4e5a22c3f5c6e72d0406fa0173ab5626/spartan_scan-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-12 14:39:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WaletLab",
"github_project": "Spartan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "spartan-scan"
}
JSON
