FindOS – Professional Go Network Reconnaissance Tool

Project Overview

FindOS is a Go‑based network reconnaissance utility designed for the initial phases of penetration testing.
It accepts an IP address or domain name and performs two primary analyses:

Cloud Proxy Detection – Determines whether the target is protected by a cloud proxy service (e.g., Cloudflare, AWS CloudFront, Azure Front Door) by:
- Resolving DNS records and checking against known IP CIDR ranges.
- Issuing an HTTP HEAD request and inspecting Server and Via headers.
- Loading additional CIDR ranges from an external data file.
OS Fingerprinting – When no proxy is detected, conducts lightweight OS fingerprinting:
- Scans common ports (80, 443, 22) with TCP SYN probes.
- Captures TTL, window size, and TCP options using gopacket.
- Performs banner grabbing on HTTP/HTTPS services.
- Returns a best‑effort OS guess and a list of open ports.

The tool follows professional software engineering practices, including modular code structure, comprehensive error handling, structured logging (Logrus), and unit testing.

Installation

# Clone the repository
git clone https://git.gostacks.org/iwasforcedtobehere/findos.git
cd findos

# Ensure Go 1.22+ is installed
go version

# Download dependencies
go mod tidy

# Build the binary
go build -o findos ./cmd/findos

Usage

# Basic usage (JSON output)
./findos -target example.com -json

# Human‑readable output with custom log level
./findos -target 192.0.2.45 -log debug

Sample Output (JSON)

{
  "target": "example.com",
  "cloud_proxy": {
    "is_proxy": true,
    "provider": "Cloudflare",
    "details": "Detected via HTTP headers"
  },
  "fingerprint": null,
  "error": ""
}

Sample Output (Human‑Readable)

Target: example.com
Cloud Proxy Detected: true (Provider: Cloudflare)
OS Guess: Linux 4.15
Open Ports:
  - 80 (http)
  - 443 (https)
  - 22 (ssh)

Technical Methodology

Cloud Proxy Detection

DNS Resolution: Uses net.DefaultResolver to resolve A/AAAA records.
CIDR Matching: Checks resolved IPs against hard‑coded CIDR maps and the external cloud_ranges.txt file.
HTTP Header Analysis: Sends a HEAD request; examines Server and Via headers for known provider signatures.
Extensibility: New providers can be added by appending CIDR blocks to cloud_ranges.txt.

OS Fingerprinting

Port Scanning: Connects to common ports with a 2‑second timeout.
Packet Crafting: Generates TCP SYN packets using gopacket to capture response characteristics (TTL, window size, TCP options).
Banner Grabbing: Retrieves service banners for HTTP/HTTPS.
Heuristics: Uses simple TTL and window size heuristics to infer the operating system (e.g., Linux, Windows, BSD). The current implementation returns “Unknown” as a placeholder for future enhancement.

Project Structure

findos/
├── cmd/
│   └── findos/
│       └── main.go          # CLI entry point
├── internal/
│   ├── clouddetect/
│   │   ├── detect.go        # Core detection logic
│   │   ├── loader.go        # Loads CIDR ranges from file
│   │   └── cloud_ranges.txt # Data file with provider CIDRs
│   ├── fingerprint/
│   │   ├── fingerprint.go   # OS fingerprinting logic
│   │   ├── packet.go        # SYN packet builder
│   │   └── packet_test.go   # Unit test for packet builder
│   └── logger/
│       └── logger.go        # Wrapper around Logrus (future)
├── go.mod
├── go.sum
└── README.md

Contribution Guidelines

Branching Model: Fork the repository and create a feature branch (git checkout -b feature/your‑feature).
Testing: Add unit tests in the corresponding *_test.go files. Run go test ./... to ensure all tests pass.
Linting: Use golint and go vet to maintain code quality.
Documentation: Keep the README and inline comments up‑to‑date.
Pull Requests: Submit PRs for review; ensure they pass the CI pipeline.

License

This project is released under the MIT License. See the LICENSE file for details.

4.2 KiB Raw Permalink Blame History Unescape Escape