The Python bindings provide a synchronous API over the async Rust engine. The GIL is released during all network I/O, so other Python threads run freely while scans execute.
Phase C adds endpoint discovery, service fingerprinting, and an async client. Phase D adds findings/reporting, passive recon (DNS, TLS, tech detection), and WAF detection. See Async API, Endpoint Discovery, Service Fingerprinting, Reconnaissance, WAF Detection, and Findings & Reports for details.
Convenience function for a single scoped port scan. Internally creates an ephemeral Client.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
target |
str |
(required) | Hostname or IP to scan |
ports |
list[int] |
(required) | Port numbers to scan |
scope |
Scope |
(required) | Authorization scope |
concurrency |
int |
100 |
Max concurrent connections |
timeout_ms |
int |
5000 |
Connection timeout (ms) |
Returns: PortScanResult
Raises:
EnforcementError— target or a port is outside scopeScanError— scan failed (network error, DNS resolution, etc.)
import eggsec
scope = eggsec.Scope.allow_hosts(["127.0.0.1"])
result = eggsec.scan_ports("127.0.0.1", [80, 443], scope)Enumerate DNS records for a domain. See Reconnaissance.
Inspect TLS/SSL configuration. See Reconnaissance.
Detect web technologies from HTTP headers. See Reconnaissance.
Detect Web Application Firewall protection. See WAF Detection.
Validate WAF bypass techniques against a target. Requires scope enforcement before dispatch. See WAF Detection.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
url |
str |
(required) | Target URL |
scope |
Scope |
(required) | Authorization scope |
bypass |
bool |
False |
Enable bypass techniques |
test_type |
str | None |
None |
Specific test type to run |
Returns: WafDetectionResult
Raises: EnforcementError, ScanError
eggsec.fuzz_http(url, scope, payload_type="all", *, method="GET", param=None, concurrency=10, timeout=30) -> FuzzResult
Perform HTTP fuzzing against a target. Requires scope enforcement before dispatch.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
url |
str |
(required) | Target URL |
scope |
Scope |
(required) | Authorization scope |
payload_type |
str |
"all" |
Payload category |
method |
str |
"GET" |
HTTP method |
param |
str | None |
None |
Target parameter |
concurrency |
int |
10 |
Max concurrent requests |
timeout |
int |
30 |
Request timeout (seconds) |
Returns: FuzzResult
Raises: EnforcementError, ScanError
eggsec.load_test_http(url, total_requests, concurrency, timeout_secs, scope, *, method="GET") -> LoadTestResult
Perform HTTP load testing against a target. Requires scope enforcement before dispatch.
Parameters:
| Name | Type | Default | Description |
|---|---|---|---|
url |
str |
(required) | Target URL |
total_requests |
int |
(required) | Total requests to send (must be > 0) |
concurrency |
int |
(required) | Concurrent workers (must be > 0) |
timeout_secs |
int |
(required) | Request timeout in seconds (must be > 0) |
scope |
Scope |
(required) | Authorization scope |
method |
str |
"GET" |
HTTP method |
Returns: LoadTestResult
Raises: EnforcementError, ScanError, ValueError (if caps are violated)
Reusable scan client bound to a scope. Preferred for repeated scans.
Constructor parameters:
| Name | Type | Default | Description |
|---|---|---|---|
scope |
Scope |
(required) | Authorization scope |
mode |
str |
"manual" |
"manual" or "automation" |
concurrency |
int |
100 |
Default max concurrent connections |
timeout_ms |
int |
5000 |
Default connection timeout (ms) |
Raises: ValueError — if mode is not "manual" or "automation".
Scan ports on a target. Keyword-only parameters override client defaults for this call.
Raises: EnforcementError, ScanError
Scan HTTP endpoints on a web server. The base_url host must be in scope.
Raises: EnforcementError, ScanError
Client.fingerprint_services(host, ports, *, concurrency=None, timeout_ms=None) -> FingerprintScanResult
Fingerprint services on open ports by analyzing banners and response patterns.
Raises: EnforcementError, ScanError
Enumerate DNS records for a domain.
Raises: EnforcementError, ScanError
Inspect TLS/SSL configuration for a host.
Raises: EnforcementError, ScanError
Detect web technologies from HTTP response headers.
Raises: EnforcementError, ScanError
Detect Web Application Firewall protection.
Raises: EnforcementError, ScanError
Validate WAF bypass techniques. Uses the client's internal scope for enforcement.
Raises: EnforcementError, ScanError
Client.fuzz_http(url, payload_type="all", *, method="GET", param=None, concurrency=10, timeout=30) -> FuzzResult
Perform HTTP fuzzing. Uses the client's internal scope for enforcement.
Raises: EnforcementError, ScanError
Client.load_test_http(url, total_requests, concurrency, timeout_secs, *, method="GET") -> LoadTestResult
Perform HTTP load testing. Uses the client's internal scope for enforcement.
Raises: EnforcementError, ScanError, ValueError
Read-only property. Returns the client's scope.
Read-only property. Returns the client's execution mode.
client = eggsec.Client(
scope=eggsec.Scope.allow_hosts(["10.0.0.0/24"]),
concurrency=200,
)
result = client.scan_ports("10.0.0.1", [22, 80])with eggsec.Client(scope) as client:
result = client.scan_ports("10.0.0.1", [80, 443])
# Client resources releasedFrozen scope configuration. Created via static factory methods, not a constructor.
Allow specific hostnames or CIDRs.
scope = eggsec.Scope.allow_hosts(["example.com", "10.0.0.0/8"])Allow only CIDR ranges.
scope = eggsec.Scope.allow_cidrs(["192.168.0.0/16", "10.0.0.0/8"])Deny all targets. Useful as a safety default.
Load scope from a TOML or YAML file. Raises ScopeError on parse failure.
Check if a target is within scope.
Check if a port is within scope.
Immutable scan result. Returned by scan_ports() and Client.scan_ports().
| Field | Type | Description |
|---|---|---|
target |
str |
Scanned host |
open_ports |
list[OpenPort] |
Open ports found |
scanned_ports |
int |
Total ports attempted |
elapsed_ms |
int |
Scan duration in ms |
stats |
ScanStats |
Aggregate stats |
Methods:
to_dict() -> dict— convert to a plain Python dictionaryto_json() -> str— serialize to a JSON string
| Field | Type | Description |
|---|---|---|
port |
int |
Port number |
protocol |
str |
Always "tcp" (Phase B) |
service |
str |
Service name (e.g. "http", "ssh") |
banner |
str | None |
Banner text, if captured |
confidence |
float |
Service detection confidence (0.0–1.0) |
| Field | Type | Description |
|---|---|---|
ports_scanned |
int |
Ports attempted |
total_open |
int |
Open ports found |
elapsed_ms |
int |
Duration in ms |
Helper for building port lists. Use static factory methods.
ports = eggsec.PortRange.list([22, 80, 443])
ports = eggsec.PortRange.range(1, 1024)
ports = eggsec.PortRange.top_100()
# Access the list via the .ports property
client.scan_ports("10.0.0.1", ports.ports)Scan timing profiles. Not yet wired to scan parameters in Phase B; provided for API completeness.
preset = eggsec.TimingPreset.normal()Available: paranoid, sneaky, polite, normal, aggressive, insane.
Configuration for endpoint discovery scans. See Endpoint Discovery.
Result of an endpoint scan. See Endpoint Discovery.
Individual endpoint finding. See Endpoint Discovery.
Result of a service fingerprint scan. See Service Fingerprinting.
Individual service fingerprint. See Service Fingerprinting.
Evidence supporting a fingerprint detection.
Confidence level for a fingerprint detection.
Finding severity enum. Values: CRITICAL, HIGH, MEDIUM, LOW, INFO.
eggsec.Severity.HIGH
eggsec.Severity.from_str("high") # case-insensitiveSupporting evidence for a finding.
| Field | Type | Description |
|---|---|---|
kind |
str |
Evidence type (e.g. "header", "body") |
value |
str |
Evidence content |
Individual security finding. See Findings & Reports.
Collection of findings with filtering and bulk export. See Findings & Reports.
Aggregated findings document. See Findings & Reports.
DNS enumeration result. See Reconnaissance.
MX record entry. See Reconnaissance.
SOA record entry. See Reconnaissance.
TLS inspection result. See Reconnaissance.
Certificate details. See Reconnaissance.
TLS security issue. See Reconnaissance.
Technology detection result. See Reconnaissance.
Detected technologies. See Reconnaissance.
WAF detection result. See WAF Detection.
The callback system provides push-based notification during scan execution. All sinks isolate errors -- a failing callback is logged and never propagates to the caller.
from eggsec import (
Scope, Client, AuditSink, FindingSink,
ArtifactSink, ProgressSink, EventConsumer,
)
def on_audit(event):
print(f" audit: {event['operation_id']}")
def on_finding(finding):
print(f" finding: {finding['title']}")
def on_progress(pct, msg):
print(f" {pct:.0f}% {msg}")
client = Client(Scope.allow_hosts(["example.com"]))
# Sinks are wired into the scan pipeline
# (API varies by operation; consult individual tool docs)For high-throughput scenarios, BackpressureChannel drops the oldest
event when the buffer is full:
from eggsec import BackpressureChannel, EventEnvelope
channel = BackpressureChannel(capacity=256)
channel.send(event)
received = channel.try_recv() # EventEnvelope or None
print(channel.total_dropped) # events lost to backpressureQueues callbacks with bounded capacity:
from eggsec import CallbackScheduler
scheduler = CallbackScheduler(capacity=1000)
scheduler.enqueue(event)
events = scheduler.drain()Zero-copy binary buffer with PEP 3118 support:
from eggsec import BinaryBuffer
buf = BinaryBuffer(b"\x00\x01\x02")
print(len(buf)) # 3
print(buf.hex()) # "000102"
mv = memoryview(buf) # zero-copy memoryviewDeferred file loading for large artifacts:
from eggsec import LazyArtifact, ArtifactMeta
meta = ArtifactMeta("capture.pcap", "pcap", "application/octet-stream", 1024000)
artifact = LazyArtifact("/tmp/capture.pcap", meta)
# Metadata available without I/O
print(artifact.name(), artifact.size_bytes())
# Load on demand
data = artifact.load() # returns BinaryBuffer
artifact.unload() # free memoryPage-based iteration:
from eggsec import PaginatedResults
results = PaginatedResults(items, page_size=50)
print(results.total_pages())
# Iterate page by page
for page_num in range(results.total_pages()):
page = results.get_page(page_num)
process(page)
# Or iterate item by item
for item in results:
process(item)EggsecError
├── ConfigError
├── ScopeError
├── EnforcementError
├── NetworkError
├── ScanError
├── TimeoutError
├── FeatureUnavailableError
├── SerializationError
└── InternalError
All exceptions inherit from EggsecError, which inherits from Python's built-in Exception.