up

README.md

@@ -0,0 +1,119 @@
+# 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.