Metadata-Version: 2.3
Name: nyx-toolkit
Version: 0.1.1
Summary: Modular security toolkit for recon, scanning, and HTTP inspection.
Keywords: security,scanner,recon,pentesting,network,cli
Author: Moonflower-labs
Author-email: Moonflower-labs <134706556+Moonflower-labs@users.noreply.github.com>
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Topic :: Internet
Requires-Dist: dnspython>=2.8.0
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/Moonflower-labs/nyx
Project-URL: Repository, https://github.com/Moonflower-labs/nyx
Project-URL: Issues, https://github.com/Moonflower-labs/nyx/issues
Description-Content-Type: text/markdown

# nyx-toolkit

Modular security toolkit for recon, scanning, and HTTP inspection.  
Minimal dependencies — stdlib only except `dnspython` for DNS resolution.

## ⚠️ Legal Disclaimer

**nyx-toolkit is intended for authorized security testing and educational purposes only.**  
Only use this tool against systems you own or have explicit written permission to test.  
Unauthorized scanning may be illegal in your jurisdiction. The authors accept no liability for misuse.

## Installation

```bash
pip install nyx-toolkit
```

Or from source:

```bash
git clone https://github.com/Moonflower-labs/nyx
cd nyx
uv sync
```

## Usage

```
nyx <command> <target> [options]
```

## Commands

### `scan`

TCP connect scan or SYN stealth scan — find open ports on a host or CIDR range.

```bash
nyx scan example.com
nyx scan example.com --ports 1-1024
nyx scan example.com --ports 80,443,8080
nyx scan example.com --ports full --concurrency 200
nyx scan 192.168.1.0/24 --ports common
nyx scan example.com --show-all
nyx scan example.com --banners
nyx scan example.com --output json
sudo nyx scan example.com --stealth
sudo nyx scan example.com --stealth --ports 1-1024 --output json
```

| Flag                | Default  | Description                                                 |
| ------------------- | -------- | ----------------------------------------------------------- |
| `-p, --ports`       | `common` | Port expression: `80`, `1-1024`, `80,443`, `common`, `full` |
| `-t, --timeout`     | `1.0`    | Per-port timeout in seconds                                 |
| `-c, --concurrency` | `100`    | Concurrent threads                                          |
| `-o, --output`      | `plain`  | Output format: `plain` or `json`                            |
| `--show-all`        | off      | Show closed and filtered ports, not just open               |
| `--banners`         | off      | Grab service banners from open ports                        |
| `--stealth`         | off      | SYN scan — never completes handshake (requires root)        |

**Named port sets**

| Name     | Ports                                                                          |
| -------- | ------------------------------------------------------------------------------ |
| `common` | 21, 22, 23, 25, 53, 80, 110, 143, 443, 445, 3306, 3389, 5432, 6379, 8080, 8443 |
| `full`   | 1–65535                                                                        |

**Scan modes**

| Mode                      | How                                                             | Root required |
| ------------------------- | --------------------------------------------------------------- | ------------- |
| TCP connect (default)     | Full 3-way handshake via `connect()`                            | No            |
| SYN stealth (`--stealth`) | Sends SYN, reads SYN-ACK, sends RST — handshake never completes | Yes           |

**Banner grabbing**

Services that announce themselves on connect (SSH, FTP, SMTP, etc.) are read directly. HTTP/HTTPS ports receive a `HEAD /` probe and return the `Server:` header.

---

### `http`

Inspect HTTP responses — status, headers, redirect chain, TLS info, and security header audit.

```bash
nyx http example.com
nyx http https://example.com --no-follow
nyx http example.com --output json
```

| Flag            | Default | Description                      |
| --------------- | ------- | -------------------------------- |
| `-t, --timeout` | `10.0`  | Request timeout in seconds       |
| `-o, --output`  | `plain` | Output format: `plain` or `json` |
| `--no-follow`   | off     | Do not follow redirects          |

**Security headers audited**

`strict-transport-security`, `content-security-policy`, `x-frame-options`,
`x-content-type-options`, `referrer-policy`, `permissions-policy`

> Note: TLS certificate verification is disabled for HTTPS banner grabbing — this is intentional for a security scanner.

---

### `recon`

Subdomain enumeration and DNS record lookup.

```bash
nyx recon example.com
nyx recon example.com --no-subdomains
nyx recon example.com --concurrency 100
nyx recon example.com --output json
```

| Flag                | Default | Description                                  |
| ------------------- | ------- | -------------------------------------------- |
| `-c, --concurrency` | `50`    | Concurrent threads for subdomain brute-force |
| `-o, --output`      | `plain` | Output format: `plain` or `json`             |
| `--no-subdomains`   | off     | Skip subdomain enumeration, DNS only         |

Resolves A, AAAA, MX, NS, and TXT records via `dnspython`. Brute-forces subdomains against a 60-entry wordlist covering common subdomains (`www`, `api`, `mail`, `dev`, `staging`, `admin`, `git`, `vpn`, and more).

---

## Architecture

```
src/nyx/
  cli.py              entry point, argument parsing, subparsers
  commands/
    scan.py           port scanning logic
    http.py           HTTP inspection logic
    recon.py          recon and subdomain enumeration
  core/
    network.py        hostname resolution, IP validation, CIDR expansion
    utils.py          port expression parsing, named port sets
    output.py         Result dataclass, colored printing, JSON serialization
    scanner.py        TCP connect scan, concurrent scanning, banner grabbing
    syn.py            raw packet construction, SYN stealth scan
```

**Design principles**

- `core/` is pure logic — no CLI, no printing, no side effects
- `commands/` are thin — receive already-parsed values from `cli.py` and call into `core/`
- `cli.py` owns all argument parsing via subparsers
- Minimal dependencies — stdlib only except `dnspython` for real DNS resolution

---

## Notes

- TCP connect scan requires no root privileges
- SYN stealth scan requires root (`sudo`) on both macOS and Linux — uses raw sockets
- `scanme.nmap.org` is a safe host to test scanning against (maintained by the Nmap project)

---

## License

MIT
