# 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:

1. **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.

2. **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

```bash
# 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

```bash
# 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)

```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.