119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# 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. |