<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
<!-- NERF is a trademark of defconxt. -->
# Python Security Tools — API Reference

## Scapy

```bash
# ARP scan
python3 -c "from scapy.all import *; ans,_ = srp(Ether(dst='ff:ff:ff:ff:ff:ff')/ARP(pdst='192.168.1.0/24'), timeout=3, verbose=0); print(ans.summary())"

# TCP SYN scan (requires root)
python3 -c "from scapy.all import *; ans,_ = sr(IP(dst='target')/TCP(dport=[80,443],flags='S'), timeout=2, verbose=0); ans.summary()"

# ICMP ping sweep
python3 -c "from scapy.all import *; ans,_ = sr(IP(dst='192.168.1.0/24')/ICMP(), timeout=2, verbose=0); print([r[1].src for r in ans])"

# DNS query
python3 -c "from scapy.all import *; ans = sr1(IP(dst='8.8.8.8')/UDP()/DNS(rd=1,qd=DNSQR(qname='example.com')), verbose=0); print(ans.summary())"

# Traceroute
python3 -c "from scapy.all import *; traceroute('example.com', maxttl=20)"
```

## Paramiko

```python
# SSH command execution
import paramiko
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect('host', username='user', password='pass')
stdin, stdout, stderr = client.exec_command('id')
print(stdout.read().decode())
client.close()

# SFTP file transfer
sftp = client.open_sftp()
sftp.get('/etc/passwd', '/tmp/passwd_copy')
sftp.close()

# Key-based authentication
key = paramiko.RSAKey.from_private_key_file('/path/to/key')
client.connect('host', username='user', pkey=key)
```

## Impacket

```bash
# SMB enumeration
python3 -m impacket.smbclient target -u user -p pass

# Get TGT (Kerberos)
python3 -m impacket.getTGT domain/user:pass -dc-ip 10.0.0.1

# Secretsdump (requires DA)
python3 -m impacket.secretsdump domain/user:pass@target

# WMI execution
python3 -m impacket.wmiexec domain/user:pass@target "whoami"

# PSExec
python3 -m impacket.psexec domain/user:pass@target
```

## Socket Library

```python
import socket

# TCP connect
sock = socket.create_connection(('host', 80), timeout=3)
sock.send(b'HEAD / HTTP/1.0\r\n\r\n')
response = sock.recv(4096)
sock.close()

# DNS resolution
socket.getaddrinfo('example.com', 443)

# Reverse DNS
socket.gethostbyaddr('8.8.8.8')

# Service name lookup
socket.getservbyport(443, 'tcp')  # 'https'
```

## asyncio Networking

```python
import asyncio

async def tcp_connect(host: str, port: int, timeout: float = 2.0) -> bool:
    try:
        reader, writer = await asyncio.wait_for(
            asyncio.open_connection(host, port), timeout=timeout
        )
        writer.close()
        await writer.wait_closed()
        return True
    except (asyncio.TimeoutError, ConnectionRefusedError, OSError):
        return False

# Concurrent scanning with semaphore
async def scan_with_limit(host, ports, concurrency=100):
    sem = asyncio.Semaphore(concurrency)
    async def limited_scan(port):
        async with sem:
            return await tcp_connect(host, port)
    return await asyncio.gather(*[limited_scan(p) for p in ports])
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Scan completed, no open ports / no valid creds |
| 1 | Findings detected (open ports, valid creds) |
| 2 | Runtime error or missing dependency |
