Darkproxy AI Coding Guidelines

Project Overview

Darkproxy is a multi-container Docker stack enabling anonymous proxying across darknet (I2P, Tor) and clearnet. It chains SOCKS5 proxies through custom DNS resolvers, combining Yggdrasil networking, CoreDNS service orchestration, and blockchain-based TLD resolvers (Alfis, EmerCoin, meshname).

Architecture

Fixed container IPs on darkproxy network (10.5.0.0/16):

10.5.0.2: i2pd_yggdrasil - I2P + Yggdrasil IPv6 tunneling
10.5.0.3: alfis - Blockchain resolver for .anon/.ygg/.btn/.conf TLDs
10.5.0.4: coredns - CoreDNS (PopuraDNS) DNS orchestration hub
10.5.0.5: unbound - Recursive clearnet DNS
10.5.0.6: pihole - DNS filtering + upstream forwarder
10.5.0.7: tor_yggdrasil - Tor + Yggdrasil tunneling
10.5.0.8: dark3proxy - SOCKS5/HTTP proxy (main entrypoint)
10.5.0.9: emc - EmerCoin resolver for .emc/.coin/.lib domains

Data flow: Client → dark3proxy (10.5.0.8:1080 SOCKS5) → pihole DNS (10.5.0.6) → coredns (10.5.0.4) → TLD-specific resolvers → upstream SOCKS backends (i2pd/tor).

Key Workflows

Build custom images (with version pinning via build args):

I2P: cd i2pd_yggdrasil_docker/src && ./make_docker_image.sh (sets I2PD_VERSION=2.58.0, YGGDRASIL_VERSION=v0.5.12, UBUNTU_VERSION=24.04)
Tor: cd tor_yggdrasil_docker && ./build_image.sh (same versions via git describe fallback)
3proxy: No build script—uses GitHub release binary download in Dockerfile

Deploy/Debug:

Start: docker-compose up --build from root
Logs: docker-compose logs -f coredns (or dark3proxy, i2pd_yggdrasil, tor_yggdrasil)
Shell: docker exec -it darkdns /bin/sh (use container_name from compose)
Health: Each service has healthcheck or ping-based validation in entrypoint

Add new TLD resolver:

In docker-compose.yml: add new service with fixed IP in 10.5.0.x range, ensure internal network access
In PopuraDNS/Corefile: add block like newtld.:53 { acl { allow net 10.0.0.0/8 ...; block }; forward . 10.5.0.X:53 }
Rebuild coredns: docker-compose up --build coredns

Conventions

Secrets/Environment: Stored in secrets/ directory (tz.txt for timezone, YGGDRASIL_GENERATE_KEYS.txt for key generation). Mounted as Docker secrets, referenced in environment via /run/secrets/.

Proxy Routing Logic (in 3proxy/first-instanse.cfg):

Parent rules chain traffic: i2p domains → i2pd SOCKS (10.5.0.2:4447), onion → tor SOCKS (10.5.0.7:9050), Yggdrasil (200::/7) → local SOCKS, clearnet → tor fallback
Blacklist format: {{vk.com,ok.ru,...}} (blocks these domains)

DNS Stacking: pihole (ad-filtering) → coredns (routing) → specialists. pihole upstreams to coredns (10.5.0.4), coredns forwards TLDs to resolvers. ACLs in Corefile block external networks; only 10.0.0.0/8, 127.0.0.1, fc00::/7 allowed.

Yggdrasil Key Generation: Services i2pd_yggdrasil and tor_yggdrasil run Python utils (yggdrasil_get_keys, yggdrasil_find_public_peers) in entrypoint—generates strong keys + finds optimal peers unless YGGDRASIL_GENERATE_KEYS=false.

Networking: All services require sysctls: net.ipv6.conf.all.disable_ipv6=0 for Yggdrasil IPv6. Tunneling services (i2pd_yggdrasil, tor_yggdrasil) need privileged: true, cap_add: NET_ADMIN, /dev/net/tun:/dev/net/tun.

Examples

Port Mapping (via Yggdrasil IP 100.117.196.19): SOCKS on 2000→1080, 3proxy-eagle web 2002→8161, I2P console 2001→7070
Config Mounting: Read-only volumes for configs—e.g., ./unbound/unbound.conf:/opt/unbound/etc/unbound/unbound.conf
Image Tagging: Custom builds tag as service_name:${TAG_VERSION} (git tag) and :latest; published to registry (host60/ prefix in docker-compose)

Reference files: docker-compose.yml, PopuraDNS/Corefile, 3proxy/first-instanse.cfg, i2pd_yggdrasil_docker/src/make_docker_image.sh, tor_yggdrasil_docker/build_image.sh /home/sommopfle/darkproxy/.github/copilot-instructions.md

4.1 KiB Raw Blame History