xiaoliang02

# Tool List This is an AI-powered TCP intranet penetration tool that can be used by AI intelligent agents (through MCP). It is based on the Go language and uses a C/S architecture, consisting of a public network server `nattserver` and an intranet client `nattuser`. The server is responsible for public network listening, client authorization, tunnel status, and traffic statistics; the client is responsible for connecting to the server, binding local target services, and forwarding public network access traffic to the intranet TCP service. The current version only supports TCP port penetration and does not include UDP, HTTP domain forwarding, or P2P hole punching. **Note: Before using or compiling this software, you must read, understand, and agree to the contents of the [Disclaimer](DISCLAIMER.md). If you do not agree, you can choose other similar software such as FRP, Pea2Shell, Ngrok, etc. It is prohibited to use this software to engage in any activities that violate the laws and regulations of the People's Republic of China and the location where the software is deployed.** ## Software Download 1. Release page of the current open-source project 2. Baidu Netdisk link: [https://pan.baidu.com/s/1SvAqFQfEbizim0t7q6beeQ?pwd=6666](https://pan.baidu.com/s/1SvAqFQfEbizim0t7q6beeQ?pwd=6666) ## Video Introduction and Detailed Tutorial - Detailed tutorial: [https://www.bilibili.com/video/BV14FNg6QELL/?spm_id_from=333.337.search-card.all.click](https://www.bilibili.com/video/BV14FNg6QELL/?spm_id_from=333.337.search-card.all.click) ## Core Features - TCP port penetration, supporting multiple clients and multiple tunnels concurrently. - Server-side web console: client authorization, tunnel management, traffic monitoring, configuration, auditing, and MCP management. - Client-side web console: tunnel connection, local target binding, connection status, configuration, auditing, and MCP management. - SQLite persistence of users, client authorization, tunnels, connections, configuration, and traffic statistics. - First-time startup initialization wizard, supporting custom administrator account password, production/testing mode, and web console HTTPS. - Login security: SM2 encrypted password, image verification code, JWT, user agreement checkbox, and same IP login failure progressive ban. - Password and secret key hash using SM3 salt value format. - Audit log written to `logs/audit/YYYY-MM-DD.jsonl`. - MCP using standard Streamable HTTP JSON-RPC, supporting Codex and other AI tools for automatic discovery and invocation. ## Project Structure ```text Current project directory path\natt nattserver\ Server-side project nattuser\ Client-side project skills\ Project AI Skill ``` Server-side default runtime parent directory: ```text nattserver\xiaoliang02_server\ config\config.json data\nattserver.db data\sm2_private.pem data\sm2_public.pem logs\YYYY-MM-DD.log logs\audit\YYYY-MM-DD.jsonl ssl\web.crt ssl\web.key ``` Client-side default runtime parent directory: ```text nattuser\xiaoliang02_user\ config\config.json data\nattuser.db data\sm2_private.pem data\sm2_public.pem logs\YYYY-MM-DD.log logs\audit\YYYY-MM-DD.jsonl ssl\web.crt ssl\web.key ``` Default startup only reads the `config.json` in the above parent directory. Explicitly passing `-config <path>` still supports `.json`, `.yaml`, and `.yml`. ## Default Ports Server-side: | Purpose | Default value | | --- | --- | | Web management backend | `0.0.0.0:25510` | | MCP interface | `0.0.0.0:25510/mcp` | | Client control connection | `0.0.0.0:25511` | | Client data connection | `0.0.0.0:25512` | | Public network mapping port range | `0-65535` | Client-side: | Purpose | Default value | | --- | --- | | Web management backend | `127.0.0.1:25520` | | MCP interface | `127.0.0.1:25520/mcp` | | Default server control port | `25511` | | Default server data port | `25512` | ## Quick Start ### 1. Start the Server-side ```powershell cd Current project directory path\natt\nattserver go run . ``` Access for the first time: ```text http://127.0.0.1:25510/init.html ``` Initialization page divided into two steps: 1. Configure running mode, port, database path, and web console HTTPS. 2. Create console administrator account password and check "I have read and agreed to the User Agreement". ### 2. Start the Client-side ```powershell cd Current project directory path\natt\nattuser go run . ``` Access for the first time: ```text http://127.0.0.1:25520/init.html ``` Client-side initialization only configures default control port and default data port, not default server address. Server address is filled in when adding a new tunnel connection. ### 3. Explicit Configuration Startup ```powershell cd Current project directory path\natt\nattserver go run . -config xiaoliang02_server\config\config.json cd Current project directory path\natt\nattuser go run . -config xiaoliang02_user\config\config.json ``` ### 4. Compilation ```powershell cd Current project directory path\natt\nattserver go build -p 1 ./... cd Current project directory path\natt\nattuser go build -p 1 ./... ``` Compiled exe placed in an empty folder and started directly, the program will take the exe location directory as the working directory and automatically create `xiaoliang02_server/` or `xiaoliang02_user/`. ## Basic Usage Process 1. Start and initialize `nattserver`. 2. Add client authorization on the server-side backend, and copy the generated client secret key. 3. Add TCP tunnel on the server-side backend, fill in the public network listening address and public network listening port; local address and local port are not filled on the server-side. 4. Check "nattuser connection and automatically start" as needed. 5. Start and initialize `nattuser`. 6. Add tunnel connection on the client-side backend, fill in server address, control port, data port, server tunnel secret key, local target address, and local target port. 7. Start client tunnel connection, and access the intranet TCP service through the server's public network port. Tunnel ownership rules: - `nattserver` manages public network listening ports, status, secret keys, and traffic. - `nattuser` manages server address, server port, tunnel secret key, and local target. - The same server tunnel can only be occupied by one online client at a time. - Server tunnel is in "待连接" state and opens automatic startup when the client is not online and clicks "启动". - Client disconnection due to network anomalies will automatically reconnect; if clicked "断开" on the client-side backend, it will close the connection and automatic reconnection, and must click "连接" again to restore automatic reconnection. - Server status details are "隧道控制连接已离线" recoverable errors, which will automatically recover the tunnel when the original client comes online or the heartbeat arrives. - Server stops the tunnel and will send a stop instruction and heartbeat response to the client, and the client status details will display "服务端暂停了隧道连接，请通知服务端人员启动隧道". ## MCP Usage Both sides of MCP use standard Streamable HTTP JSON-RPC: ```text POST http://<host>:<port>/mcp ``` Authentication method: ```text Authorization: Bearer <MCP_KEY> ``` or ```text X-MCP-Token: <MCP_KEY> ``` Supported methods: - `initialize` - `notifications/initialized` - `ping` - `tools/list` - `tools/call` Server-side common tools: - `server.list_clients` - `server.get_client` - `server.list_tunnels` - `server.create_tunnel` (omitting `auto_start` defaults to `true`, creating and entering a pending connection state) - `server.start_tunnel` - `server.stop_tunnel` - `server.delete_tunnel` - `server.get_dashboard` Client-side common tools: - `client.list_tunnel_connections` - `client.list_servers` - `client.create_tunnel_connection` - `client.delete_tunnel_connection` - `client.connect_tunnel` - `client.connect_server` - `client.disconnect_tunnel` - `client.disconnect_server` - `client.list_tunnels` - `client.get_network_status` Client-side new tunnel connection tool parameters: `name`, `server_host`, `client_secret`, `local_host`, `local_port` are required; `server_port`, `data_port` can be omitted, using the default control port and data port in the client-side configuration. Tool discovery example: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` Tool invocation example: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "server.list_tunnels", "arguments": { "page": 1, "page_size": 20 } } } ``` ## Test Server-side: ```powershell cd Current project directory path\natt\nattserver go test ./... -count=1 -p 1 go build -p 1 ./... ``` Client-side: ```powershell cd Current project directory path\natt\nattuser go test ./... -count=1 -p 1 go build -p 1 ./... ``` If Windows test temporary exe is occupied, set an independent `GOTMPDIR` and try again. ## Related Documents - [需求文档.txt](需求文档.txt) - [使用文档.md](使用文档.md) - [开发任务拆分TODO.md](开发任务拆分TODO.md) - [项目 AI Skill](skills/xiaoliang02-natt/SKILL.md) - [项目模块地图](skills/xiaoliang02-natt/references/project-map.md) ## Code Repository GitCode: ```text https://gitcode.com/gongjuliang/xiaoliang02 ``` ## Open-source License Applicable ### 1. Default License Agreement This software is released under the **GNU Affero General Public License v3.0 (AGPL-3.0)** open-source license by default. Unless you meet the exception conditions specified in Section 2, your use, modification, and distribution behavior will be bound by AGPL-3.0. The full text of AGPL-3.0 can be found in the `LICENSE` file in the project root directory or visit: https://www.gnu.org/licenses/agpl-3.0.html ### 2. Exception License Conditions You can obtain the **MIT open-source license** authorization for this software when you meet all of the following conditions: 1. **Follow requirements**: You follow the official account "工具人小良" on any of the following platforms and become a fan, and the follow status is valid: - Bilibili - Douyin - Kuaishou - Xiaohongshu 2. **Identity requirements**: Your account subject is a **natural person** (not an enterprise or individual business). Note: Enterprises or individual businesses need to contact the developer to obtain the MIT open-source authorization letter; otherwise, please follow the AGPL-3.0 open-source license. ### 3. Authorization Restrictions and Revocation 1. **Irtransferable**: MIT authorization is only for personal use and cannot be transferred, rented, or lent to a third party. 2. **Continuous obligation**: After obtaining MIT authorization, if you cancel follow or change your account subject to an enterprise/organization, the authorization will automatically terminate. 3. **Violation consequences**: If you do not complete the exception license conditions and violate the AGPL-3.0 open-source license, the developer has the right to pursue breach of contract. The distributed derivative works still need to comply with the AGPL-3.0 license. 4. **Retrospective effect**: If MIT authorization is revoked/terminated, subsequent distribution behavior must restore compliance with AGPL-3.0. ### 4. Conflict Resolution [Disclaimer](DISCLAIMER.md) and AGPL-3.0 constitute complete license terms. In case of conflict, the priority is as follows: 1. Mandatory terms in [Disclaimer](DISCLAIMER.md) (especially disclaimer and liability limitation clauses) 2. AGPL-3.0 license text (for natural persons who meet the above exception license conditions, this item is MIT protocol)