Overview

lolnetscan is a single-file Bash network discovery and port-probing tool.
It expands CIDR, ranges, and lists into target IPs, verifies host liveness, and probes TCP/UDP ports using /dev/tcp and nc.
Designed for constrained footholds: minimal dependencies, small footprint, and easy auditability.

Quick install & run

Clone and run (no install required):

git clone https://github.com/ousbaailyas/lolnetscan.git
chmod +x lolnetscan/lolnetscan
./lolnetscan/lolnetscan -host 192.168.0.1-192.168.0.10 -p 53,80 -u

One-liner (streaming from raw):

bash <(curl -sSL https://raw.githubusercontent.com/ousbaailyas/lolnetscan/master/lolnetscan) -host 10.0.0.1/24 -p 80

Design goals

• Minimal footprint: rely on POSIX/Bash and commonly-available tools (nc, timeout, coreutils).

• Auditable: single script, small surface area; easy to review and adapt.

• Flexible input: support comma lists, dash ranges, and CIDR notation.

• Low-noise probing: fast checks, short timeouts, and optional UDP mode to avoid excessive chatter.

• Operational safety: no persistence, no external binaries beyond standard toolchain.

Architecture & key components

1. Input normalizer

   • Accepts -host values in formats: ip, start-end, a,b,c, and CIDR (x.x.x.x/24).

   • Canonicalizes inputs and emits a single newline-separated list of IPv4 addresses.

2. IP conversion utilities

   • ip_to_int() / int_to_ip() convert IPv4 to 32-bit integer and back.

   • Used to iterate ranges and compute network/broadcast addresses for CIDR expansion.

3. Port parser

   • Accepts comma-separated ports and ranges (80,443,8000-8010).

   • Validates numeric range (1–65535) and filters invalid entries.

4. Liveness check

   • Optional ping-based discovery for host liveness (fast discovery mode).

   • Default behavior: probe ports directly and infer liveness from open responses.

5. TCP probing

   • Uses Bash /dev/tcp/$ip/$port wrapped in timeout for sub-second probes.

   • Advantages: zero-dependency on external TCP-only tools; minimal footprint.

6. UDP probing

   • Uses nc -zu -w1 where available; classifies replies as "open" vs "closed/filtered" heuristically.

   • Notes: UDP is inherently unreliable; results are best-effort.

7. Output layer

   • Human-friendly log prefixes ([INF], [ERR]) and clear open/closed messages.

   • Designed for easy parsing by downstream scripts (grep/awk).

Usage examples

• TCP scan single host:

  ./lolnetscan -host 192.168.1.10 -p 22

• TCP scan CIDR (skip ping):

  ./lolnetscan -host 10.0.0.0/24 -p 80

• UDP scan a host range:

  ./lolnetscan -host 192.168.1.1-192.168.1.50 -p 53,161 -u

Implementation notes (critical details)

• /dev/tcp usage: the script uses Bash's /dev/tcp redirect for TCP probes. This is compact but requires Bash with networking enabled. Use timeout to bound waits.

• Netcat fallback: when /dev/tcp is unsuitable (older shells), nc is used where present. The script detects availability.

• Timeout strategy: timeouts are short (1s default) to keep scans fast on footholds. Increase timeouts only when network conditions warrant it.

• CIDR expansion: the script excludes network and broadcast addresses when enumerating hosts.

• Input validation: ports outside 1–65535 are discarded with a warning; malformed entries are ignored to avoid runtime errors.

Performance & limitations

• Performance: optimized for low-resource hosts; not parallelized by default to reduce noise and CPU/IO.

• Scalability: for large CIDRs or wide port ranges, performance degrades linearly. Consider batching or adding concurrency with care.

• Accuracy: UDP results are heuristic — lack of response ≠ closed port. Use UDP probes with context and follow-up validation.

• Detection risk: although the script uses native utilities and short timeouts, any active scanning generates network traffic and can be detected by defenders.

Integration & workflows

• Red-team playbook: include lolnetscan as initial reconnaissance step from ephemeral shells; pipe output into parsing scripts.

• Automation: integrate into toolchains (Ansible tasks, CI test scripts) for quick environment checks.

• Chaining: pipe open-port output to service fingerprinting or targeted probes for follow-up assessment.

Example pipeline:

./lolnetscan -host 10.0.0.0/28 -p 22,80 | grep "Open" | awk '{print $4}' | xargs -n1 -I{} nmap -sV

Hardening & safety best practices

• Add explicit consent and scope checks before running on environments you do not own.

• Prefer -host lists limited to known ranges during active engagements.

• Consider logging to ephemeral files and securely removing them after engagement.

• Avoid exposing the script on public servers containing sensitive creds or keys.

Development notes & extension ideas

• Add optional parallelism (xargs -P or background job control) with rate-limiting.

• Improve UDP fidelity with application-layer probes for specific services (e.g., DNS, NTP).

• Add JSON output mode for machine parsing.

• Implement adaptive timeouts based on observed RTTs.

Testing & validation

• Unit-test IP expansion functions with representative CIDR and range cases.

• Validate /dev/tcp probing on target platforms (Alpine, Debian, CentOS) and detect shell compatibility.

• Run controlled scans in lab environments to tune timeouts and detect false positives.

Example internal flow (concise)

1. Parse -host and -p args.

2. Expand host list (CIDR / ranges / lists).

3. Validate ports and sanitize input.

4. For each host: optional ping → port probe loop (TCP/UDP) → log result.

5. Exit with summary code.

Contribution & maintainers

• Contributions: open pull requests for bug fixes, tests, and small feature additions. Keep changes small and focused.

• Maintain style: single-file, documented functions, and defensive input handling.

License & ethics

Licensed under MIT. Use responsibly and only in authorized engagements.