wgpsec/ENScan_GO

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

ENScan_GO is an enterprise information gathering tool for security researchers and penetration testers (HW/SRC scenarios in China). It collects publicly available business information from Chinese enterprise data sources including AQC (爱企查), TYC (天眼查), KC (快查), RB (风鸟), and plugin sources (MIIT ICP备案, Coolapk, Qimai).

## Build Commands

```bash
# Local development build
go build -o enscan .

# Release build (cross-platform, uses xgo)
bash build.sh release

# Non-release build (Linux/Windows/Darwin amd64 only)
bash build.sh
```

**Requirements:**
- Go >= 1.22.1 (project uses Go 1.23.0)
- `xgo` for cross-platform builds: `go install github.com/karalabe/xgo@latest`
- `upx` for binary compression (optional)

## Running the Tool

```bash
# Generate config file (first-time setup)
./enscan -v

# Basic search
./enscan -n 小米

# Batch query from file
./enscan -f companies.txt

# Filter by investment ratio
./enscan -n 小米 -invest 100

# Deep search (grandchild companies)
./enscan -n 小米 -invest 51 --branch --deep 2

# Use specific data source
./enscan -n 小米 -type tyc
./enscan -n 小米 -type aqc,tyc

# API mode (port 31000)
./enscan --api

# MCP server mode (port 8080)
./enscan --mcp
```

## Architecture

**Interface-based design** (`interface/enscan.go`):
- `ENScan` interface: Core enterprise search with `AdvanceFilter()`, `GetCompanyBaseInfoById()`, `GetInfoByPage()`, `GetENMap()`
- `App` interface: Plugin sources with `GetInfoList()`

**Data source implementations** (`internal/`):
Each data source (aiqicha, tianyancha, kuaicha, riskbird, tycapi) implements the `ENScan` interface with:
- Main logic file (e.g., `aiqicha.go`)
- Bean file (`bean.go`) defining field mappings (`getENMap()`)

**Task queue system** (`runner/runner.go`):
- `ESJob`: Main orchestrator for batch queries
- `EnJob`: Individual enterprise query job
- `DeepSearchTask`: Recursive company relationship search
- Supports `.gob` cache files for batch query recovery

**Field mapping** (`common/config.go`):
- `EnsGo`: Field mapping structure for each API endpoint
- `ENsD`: Unified return format (keyword, name, pid, options)
- Unified output format (`ENSMapLN`) across all data sources

## Configuration

Config file location: `~/.claude/config.yaml` (generated by `./enscan -v`)

Required cookies for each data source:
- AQC: `aiqicha` cookie (full cookie including http-only fields)
- TYC: `tianyancha` cookie + `tycid` + `auth_token`
- KC: `kuaicha` cookie
- RB: `risk_bird` cookie
- MIIT: `miit_api` endpoint URL

## Key Files to Understand

- `enscan.go`: CLI entry point
- `common/flag.go`: CLI argument parsing and banner
- `common/parse.go`: Option validation and preprocessing
- `runner/enscan.go`: Core search/filter logic, deep search implementation
- `runner/api.go`: REST API server (Gin framework)
- `runner/mcpServer.go`: MCP server for AI agent integration
- `common/output.go`: Data formatting and export (JSON/XLSX)

## Available Fields

Query fields (`-field`): `icp`, `weibo`, `wechat`, `app`, `job`, `wx_app`, `copyright`, `supplier`

Deep search fields: `invest`, `branch`, `holds`, `supplier`

Data source types (`-type`): `aqc`, `tyc`, `kc`, `rb`, `tycapi`, `all`, `miit`, `coolapk`, `qimai`

## API Endpoints

REST API (`--api` mode):
- `GET /api/info?name=小米&invest=100&branch=true`
- `GET /api/pro/:type` - Pro mode for direct data source calls:
  - `advance_filter` - Search companies
  - `get_ensd` - Get field mappings
  - `get_base_info` - Company basic info by PID
  - `get_page` - Paginated data retrieval

## Notes

- No formal test suite exists in this project
- Request delays (`-delay`) recommended to avoid account anomalies on data platforms
- Cache file `enscan.gob` created for batch queries if abnormal exit occurs
- Tool uses only public data sources, no bypass/cracking capabilities