giip

네트워크 토폴로지(Net3D) API 레퍼런스

네트워크 토폴로지(Net3D) 시각화를 위해 에이전트 또는 서드파티 시스템에서 인프라 연결 데이터를 수집하고 GIIP 플랫폼으로 전송하는 API 규격을 안내합니다.

🔌 네트워크 토폴로지 페이지로 이동 →

📋 개요

Net3D 시스템은 에이전트가 수집한 데이터를 

tKVS
테이블에 적재하고, 이를 기반으로 서버-서버, 서버-DB 간의 연결 관계를 3D로 시각화합니다. 정확한 시각화를 위해 데이터의 필드명과 규격 준수가 필수적입니다.

🔐 인증 및 헤더

모든 요청은 application/x-www-form-urlencoded 형식으로 전송해야 하며, 바디(Body)에 인증 토큰을 포함해야 합니다.

  • Content-Type: 
    application/x-www-form-urlencoded; charset=utf-8
  • Body Field: 
    token=[Your Secret Key]

[!IMPORTANT] 인증은 HTTP 헤더 (

Authorization
)가 아닌, 요청 바디의 
token
필드를 통해 수행됩니다. 
token
값은 
giipAgent.cfg
의 
sk
값을 사용합니다.

🚀 주요 데이터 수집 및 전송 (Factor별 규격)

1. 인프라 인벤토리 수집 (
netinv
)

서버의 기본 사양과 네트워크 인터페이스, 라우팅 정보를 전송합니다.

  • Endpoint: 
    POST /api/giipApi?cmd=AgentAutoRegister
  • Content-Type: 
    application/x-www-form-urlencoded
  • Body Fields: 
    • token
      : 
      sk
      값 (또는 
      at
      값)
    • text
      : 
      "AgentAutoRegister"
    • jsondata
      : 아래 JSON 구조를 문자열화하여 전송

jsondata 구조 예시:

{
  "hostname": "WEB-SRV-01",
  "os": "Windows Server 2022",
  "cpu_cores": 8,
  "ipv4_local": "10.0.0.5"
}

2. 서버 간 연결 리스트 (
netstat
)

현재 서버에서 외부 서버로 연결된 TCP 세션 정보를 전송합니다.

  • Endpoint: 
    POST /api/giipApi?cmd=KVSPut
  • Content-Type: 
    application/x-www-form-urlencoded
  • Body Fields: 
    • token
      : 
      sk
      값
    • text
      : 
      "KVSPut kType kKey kFactor"
      (리터럴 고정 문자열)
    • jsondata
      : 아래 객체 구조를 문자열화하여 전송

jsondata 구조 예시:

{
  "kType": "lssn",
  "kKey": "123456",
  "kFactor": "netstat",
  "kValue": [
    {
      "remote_ip": "10.0.0.10",
      "remote_port": 8080,
      "process_name": "nginx.exe",
      "state": "ESTABLISHED"
    }
  ]
}

주의: 

state
가 
ESTABLISHED
인 항목만 토폴로지에 선(Link)으로 표시됩니다.

3. 데이터베이스 연결 정보 (
db_connections
)

애플리케이션 서버에서 DB 서버로 전송되는 쿼리 및 부하 정보를 관리합니다.

  • kFactor: 
    db_connections
  • Payload 규격: | 필드명 | 설명 | 비고 | |:---|:---|:---| | 
    client_net_address
    | 소스 서버 IP | 
    tLSvr.ips
    와 일치해야 매핑됨 | | 
    program_name
    | 실행 프로그램명 | Outgoing 노드의 라벨로 사용 | | 
    cpu_load
    | 쿼리 부하 | 링크 선의 굵기 및 파티클 속도 결정 | | 
    last_sql
    | 실행 중인 SQL | 상세 보기 모달에 표시 | | 
    query_hash
    | SQL 구문 해시 | 동일 쿼리 그룹화에 사용 |

4. 데이터베이스 리스트 조회 (
ManagedDatabaseList
)

프로젝트(csn)에 연결된 관리 대상 데이터베이스 목록을 가져옵니다.

  • text: 
    "ManagedDatabaseList [db_type]"
    (예: 
    ManagedDatabaseList mssql
    )
  • csn 지정 관련: 
    token
    (sk)에 프로젝트 정보가 내포되어 있으므로, API 호출 시 
    csn
    을 명시적으로 전달할 필요가 없습니다. 서버에서 자동으로 해결됩니다.

🔍 데이터 정합성 주의사항 (AI 가이드)

AI 에이전트가 데이터를 생성하거나 검증할 때 다음 조건을 반드시 확인하십시오.

  1. IP 매핑: 
    tLSvr.ips
    필드는 반드시 
    [{"CIDR":"10.0.0.5/24"}]
    와 같은 JSON 배열 구조여야 합니다. 단순 문자열일 경우 토폴로지에서 'External' 노드로 분리됩니다.
  2. DB 호스트 일치: 
    tManagedDatabase.db_host
    값은 에이전트가 전송하는 
    client_net_address
    와 텍스트 레벨에서 100% 일치해야 링크가 생성됩니다.
  3. JSON Depth: 데이터 전송 시 하위 오브젝트가 잘리지 않도록 충분한 깊이(Depth 10 이상)로 인코딩하십시오.

💻 언어별 전송 샘플 스크립트

실제 인프라 환경에서 데이터를 수집하고 전송하는 예제 코드입니다. 

giipAgentWin
의 구현 방식에 맞추어 **등록(AgentAutoRegister)**은 JSON, **데이터 전송(KVSPut)**은 Form-urlencoded 방식을 사용합니다.

1. PowerShell (Windows)

Windows 에이전트(

giipAgentWin
)의 동작 방식을 모사한 스크립트입니다.

# 1. 서버 등록 (AgentAutoRegister)
$sk = "YOUR_SECRET_KEY"
$apiUrl = "https://your-api.azurewebsites.net/api/giipApi?cmd=AgentAutoRegister"

$discoveryData = @{
    hostname   = $env:COMPUTERNAME
    os         = (Get-CimInstance Win32_OperatingSystem).Caption
    cpu_cores  = (Get-CimInstance Win32_Processor).NumberOfLogicalProcessors
    ipv4_local = (Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.IPAddress -ne '127.0.0.1' } | Select-Object -First 1).IPAddress
} | ConvertTo-Json -Compress

$regBody = @{ 
    token    = $sk
    text     = "AgentAutoRegister"
    jsondata = $discoveryData 
}
$resp = Invoke-RestMethod -Uri $apiUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $regBody
$lssn = $resp.lssn  # 등록 후 발급받은 LSSN 저장

# 2. 연결 정보 전송 (KVSPut netstat)
$connUrl = "https://your-api.azurewebsites.net/api/giipApi"
$connections = Get-NetTCPConnection -State Established | Select-Object -First 100 | ForEach-Object {
    @{
        remote_ip    = $_.RemoteAddress
        remote_port  = $_.RemotePort
        state        = "ESTABLISHED"
        process_name = (Get-Process -Id $_.OwningProcess -ErrorAction SilentlyContinue).ProcessName
    }
}
$payload = @{ 
    kType   = "lssn"
    kKey    = $lssn
    kFactor = "netstat"
    kValue  = $connections 
} | ConvertTo-Json -Compress -Depth 10

$putBody = @{
    token    = $sk
    text     = "KVSPut kType kKey kFactor"
    jsondata = $payload
}
Invoke-RestMethod -Uri $connUrl -Method Post -ContentType "application/x-www-form-urlencoded" -Body $putBody

2. Bash Shell (Linux)

Linux 환경에서 

curl
과 
jq
를 사용하여 전송하는 방식입니다.

#!/bin/bash
AT="YOUR_SECRET_KEY"
API_URL="https://your-api.azurewebsites.net/api/giipApi"

# 1. 서버 등록
JSON_DATA=$(cat <<EOF
{
  "hostname": "$(hostname)",
  "os": "$(cat /etc/os-release | grep PRETTY_NAME | cut -d'"' -f2)",
  "cpu_cores": $(nproc),
  "ipv4_local": "$(hostname -I | awk '{print $1}')"
}
EOF
)
RESP=$(curl -s -X POST "$API_URL?cmd=AgentAutoRegister" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$SK" \
     --data-urlencode "text=AgentAutoRegister" \
     --data-urlencode "jsondata=$JSON_DATA")
LSSN=$(echo $RESP | jq -r '.lssn')

# 2. 연결 정보 전송 (KVSPut netstat)
CONNS=$(ss -tunp | grep ESTAB | head -n 50 | awk '{print $5}' | awk -F'[: ]' '{print "{\"remote_ip\":\""$1"\",\"remote_port\":\""$2"\",\"state\":\"ESTABLISHED\"}"}' | paste -sd, -)
PAYLOAD=$(cat <<EOF
{
  "kType": "lssn",
  "kKey": "$LSSN",
  "kFactor": "netstat",
  "kValue": [$CONNS]
}
EOF
)

curl -X POST "$API_URL" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     --data-urlencode "token=$SK" \
     --data-urlencode "text=KVSPut kType kKey kFactor" \
     --data-urlencode "jsondata=$PAYLOAD"

3. Python (Cross-platform)

requests
라이브러리를 사용한 범용 스크립트입니다.

import requests
import json
import platform
import socket

AT = "YOUR_SECRET_KEY"
BASE_URL = "https://your-api.azurewebsites.net/api/giipApi"

# 1. 서버 등록
import urllib.parse, urllib.request

registration_data = {
    "hostname": socket.gethostname(),
    "os": platform.platform(),
    "cpu_cores": 8,
    "ipv4_local": socket.gethostbyname(socket.gethostname())
}

reg_payload = urllib.parse.urlencode({
    "token":    SK,
    "text":     "AgentAutoRegister",
    "jsondata": json.dumps(registration_data),
}).encode("utf-8")

req = urllib.request.Request(
    f"{BASE_URL}?cmd=AgentAutoRegister",
    data=reg_payload,
    headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
)
with urllib.request.urlopen(req) as f:
    resp = json.loads(f.read().decode("utf-8"))
    lssn = resp.get('lssn')

# 2. 연결 정보 전송 (KVSPut netstat)
payload_data = {
    "kType": "lssn",
    "kKey": lssn,
    "kFactor": "netstat",
    "kValue": [
        {"remote_ip": "10.0.0.10", "remote_port": 80, "state": "ESTABLISHED", "process_name": "python"}
    ]
}

put_payload = urllib.parse.urlencode({
    "token":    SK,
    "text":     "KVSPut kType kKey kFactor",
    "jsondata": json.dumps(payload_data),
}).encode("utf-8")

req_put = urllib.request.Request(
    BASE_URL,
    data=put_payload,
    headers={"Content-Type": "application/x-www-form-urlencoded; charset=utf-8"},
)
urllib.request.urlopen(req_put)

✅ 데이터 전송 확인 (Verification)

스크립트 실행 후 데이터가 정상적으로 수집되었는지 아래 단계로 확인하십시오.

  1. 서버 리스트 확인: 
    기본정보 관리 > 서버 인벤토리
    메뉴에서 해당 호스트네임의 서버가 등록되었고, '마지막 상태체크' 시간이 현재로 업데이트되었는지 확인합니다.
  2. 데이터베이스 매핑: DB 연결 정보를 보낼 경우, 
    client_net_address
    가 해당 서버의 IP와 정확히 일치하는지 확인하십시오.
  3. 토폴로지 뷰어: 
    /admin/network-topology
    페이지로 이동하여 노드 간의 링크(선)가 활성화되는지 확인합니다. (데이터는 전송 후 약 1~2분 내로 실시간 반영됩니다.)

🛡️ Sk3(고성능 로깅) 활용

서버 간 연결(

netstat
)이나 DB 연결(
db_connections
)과 같은 대용량 토폴로지 데이터를 전송할 때, 데이터 유실 방지와 상세한 전송 에러 분석을 위해 
giipApiSk3
엔드포인트를 사용하는 것을 권장합니다.

  • 엔드포인트: 
    https://giipfaw.azurewebsites.net/api/giipApiSk3
  • 장점: 수천 건의 연결 데이터를 
    jsondata
    로 보낼 때 발생할 수 있는 데이터 절단 현상을 방지하며, 에러 발생 시 에이전트의 상세 환경 정보와 StackTrace를 자동 기록하여 토폴로지 시각화 오류를 빠르게 해결할 수 있습니다.
  • 활용 팁: 
    KVSPut
    명령 사용 시 
    jsondata
    내에 
    kType
    , 
    kKey
    , 
    kFactor
    , 
    kValue
    를 객체 형태로 담아 Sk3를 호출하면, 복잡한 인코딩 과정 없이도 안정적으로 토폴로지 데이터를 서버에 적재할 수 있습니다.

버전: 1.3 최종 업데이트: 2026-04-10 소스 파일: 

giipv3/public/help/api-network-topology.ko.md

관련 문서:

← Previous
Network & Security Policy API
Next →
System Management API