agentic-dns

에이전틱 AI 시스템(Claude, Cursor, Windsurf, Hermes Agent, Copilot)을 위한 POSIX 네이티브 DNS 라우팅, 진단 및 텔레메트리 엔진.

agentic-dns는 순수 Bash와 Rust로 작석된 제로 의존성, 초고속 DNS 오케스트레이션 엔진입니다. 개발자 워크스테이션, 홈랩, Kubernetes 노드 및 자율 AI 에이전트를 위해 설계되었으며, 다중 계층 DNS 체인(pihole -> coredns -> dnsdist -> unbound -> dnscrypt -> VPN DNS)을 관리하고, 실시간 홉별 패킷 추석(trace)을 실행하며, 실패한 업스트림을 자동으로 우회하고(bypass), AI 코딩 어시스턴트를 위한 stdio 기반 Model Context Protocol(MCP JSON-RPC) 서버를 제공합니다.

빠른 설치 옵션

옵션 1: 한 줄 스크립트 (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/dedsecorg/agentic-dns/main/install.sh | bash

옵션 2: Docker 컨테이너 (GHCR)

docker run -d --net=host ghcr.io/dedsecorg/agentic-dns:latest

옵션 3: Node.js / npx 패키지

npx agentic-dns status

Related MCP server: dns-mcp

60초 AI 에이전트 온보딩

agentic-dns는 AI 에이전트를 위한 즉시 사용 가능한 MCP JSON-RPC 프로토콜 지원을 제공합니다.

1. Claude Code

claude mcp add agentic-dns agentic-dns mcp

2. Cursor / Windsurf / Copilot

프로젝트 또는 사용자 .mcp.json 파일에 다음을 추가하세요:

{
  "mcpServers": {
    "agentic-dns": {
      "command": "agentic-dns",
      "args": [
        "mcp"
      ],
      "env": {
        "PIHOLE_HOST": "127.0.0.1",
        "AGENTIC_DNS_API_PORT": "8099"
      }
    }
  }
}

3. Hermes Agent

hermes mcp add agentic-dns agentic-dns mcp를 실행하세요.

AI 어시스턴트 프롬트 예시

연결이 완료되면 AI 코딩 어시스턴트에게 다옴과 같이 요청하세요:

• "체인에 있는 로컬 DNS 리졸버 중 다운되었거나 비정상인 것이 있는지 확인해 줘."

• "github.com의 패킷 경로를 프백 및 아웃바운드 인테페이스에서 추적해 줘."

• "stubby를 우회하고 DNS 트래을 unbound를 통해 라우팅해 줘."

• "SQLite에서 최근 Pi-hle 리 통계를 보여 줘."

주요 기능

• 외부 종석성 제로: 핵심 POSIX Bash 실횅 + 표준 Unix 도구(dig, ss, tcpdump, nft, sqlite3, socat, jq). 유휴 RAM 사용량 제로.

• 네이티브 Model Context Protocol (MCP): dns_status, dns_query, dns_trace, dns_health, dns_routes, dns_pihole_log, dns_bypass를 AI 에이전트에 제공합니다.

• 실시간 서비스 간 추적(trace): 루프백 및 네트워크 인터페이스에서 백그라운드 tcpdump 캡처를 실행하여 패킷 홉 진행 및 지연 병목 현상을 시각화합니다.

• 자동 장애 조치(bypass): dnsdist 구성을 동적으로 재작성하고 라우팅 데몬을 리로드하여 실패한 리졸버를 밀리초 단위로 우회합니다.

• 암호화 DNS 가로채기(enforce): 비파괴적 nftables 규칙을 적용하여 Private DNS(DoT 포트 853)를 리다이렉트하고 Google DoQ(UDP/443)를 차단합니다.

• 고성능 Rust 서버(agentic-dns-server): DoT/DoH 프록시 처리 및 REST 텔레메트리를 위한 server/ 크레이트를 포함합니다.

6계층 아키텍처 파이프라인

  [Client / Mobile Device]
            |
            v
      pihole (:53)          <- Ad blocking & FTL SQLite telemetry
            |
            v
     coredns (:5352)        <- Split-horizon mesh zone routing (Tailscale / Nebula)
            |
            v
     dnsdist (:5330)        <- Dynamic load balancing & bypass failover policy
            |
   +--------+--------+
   |                 |
   v                 v
unbound (:5335)   dnscrypt-proxy (:5354) / stubby (:5360)
   |                 |
   v                 v
[VPN / Upstream]  [DoH / DoT Cloud Upstreams]

CLI 명령 빠른 참조

# View active DNS chain status and listening ports
agentic-dns status

# Execute live inter-service packet trace
agentic-dns trace google.com

# Failover failing service to backup
agentic-dns bypass stubby unbound

# Check health of all DNS listeners
agentic-dns health

# View Pi-hole query logs
agentic-dns pihole-log

# Start REST API server on port 8099
agentic-dns api

# Start stdio MCP JSON-RPC Server
agentic-dns mcp

라이선스

MIT License - 무료 및 오 소스.