🦉 owo-scan

An ultra-fast, zero-dependency, professional network scanning library and CLI tool built in modern Node.js.

Designed under the OwO brand, owo-scan helps network engineers, developers, and DevOps professionals scan hosts, run TCP port discoveries, perform forward/reverse DNS resolution, and verify latency directly from their applications or terminal.

✨ Features

• 🚀 Zero Dependencies: Zero third-party baggage, keeping packages incredibly small (~15KB) and highly secure.
• ⚡ Ultra-Fast Parallel Port Scanner: Asynchronous port scanning throttling queue ensures top speed without hitting system resource limits.
• 🌐 Comprehensive DNS Lookup: Handles A, AAAA, MX, NS, and TXT forward records, and resolves reverse IP PTR lookups instantly.
• 🛡️ Dual-Mode Ping Check: Cross-platform system ICMP ping parser with an automatic, resilient TCP port handshake connection fallback when ICMP is firewalled or restricted.
• 🎨 Stunning CLI Experience: Gorgeous color-highlighted console interface featuring Owl branding, loader spinner, and result summary tables.
• ⚙️ Fully Scriptable: Support for --json flag prints clean, script-friendly JSON payloads directly to stdout.

💻 CLI Usage

You can execute the scanner instantly without installing it using npx:

npx owo-scan 1.1.1.1

Options

| Command-line Option | Short-hand | Description | Default | |---|---|---|---| | --ports <list> | -p | Comma-separated list of ports to scan | Curated common list (23 ports) | | --timeout <ms> | -t | Socket connection timeout in milliseconds | 1000ms | | --json | -j | Silent mode, outputs raw JSON results | false | | --help | -h | Display help guidelines and menus | false |

CLI Examples

Scan a domain targeting only web services:

npx owo-scan google.com --ports 80,443,8080

Run a super-fast scan with a short timeout:

npx owo-scan 192.168.1.1 --timeout 300

Generate a JSON payload for scripting or custom parsers:

npx owo-scan 127.0.0.1 --json > results.json

🛠️ Programmatic API Usage

Install owo-scan locally inside your Node.js project:

npm install owo-scan

Integration Example

import { scan } from 'owo-scan';

// Fast network assessment
const results = await scan('google.com', {
  ports: [80, 443, 22],
  timeout: 1000
});

console.log(`Status: ${results.status.toUpperCase()}`);
console.log(`Ping Latency: ${results.ping.latency} ms`);
console.log(`Open Ports:`, results.openPorts.map(p => p.port));

Complete JSON Schema Return Value

{
  "target": "google.com",
  "resolvedIp": "142.250.180.142",
  "isDomain": true,
  "timestamp": "2026-05-29T12:00:00.000Z",
  "scanDurationMs": 142.50,
  "status": "online",
  "ping": {
    "online": true,
    "latency": 8.5,
    "packetLoss": 0,
    "method": "icmp"
  },
  "dns": {
    "type": "domain",
    "domain": "google.com",
    "A": ["142.250.180.142"],
    "AAAA": ["2404:6800:4002:800::200e"],
    "MX": ["smtp.google.com (priority: 10)"],
    "NS": ["ns1.google.com"],
    "TXT": ["v=spf1 include:_spf.google.com ~all"]
  },
  "ports": [
    { "port": 22, "status": "closed", "service": "SSH" },
    { "port": 80, "status": "open", "service": "HTTP" },
    { "port": 443, "status": "open", "service": "HTTPS" }
  ],
  "openPorts": [
    { "port": 80, "status": "open", "service": "HTTP" },
    { "port": 443, "status": "open", "service": "HTTPS" }
  ]
}

🧪 Testing

To run the test suite:

npm test

Tests run completely without dependencies using the built-in node:assert test module.

🔒 Security

For reporting vulnerabilities, please consult SECURITY.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed with 💖 by OwO © 2026. All rights reserved.