파수 FED 연결

대상: 회사의 파수(Fasoo) DRM 관리자 · 커넥터 운영자 선행 조건: 커넥터 v0.2.23 이상 설치 완료 (Connector 설치 가이드) · 서버 사양은 커넥터 서버 권장 사양 함께 보실 문서: 문서 보안(DRM) 연동 가이드 · Microsoft Purview(MIP) 직접 연결 가이드

이 기능이 하는 일

파수 FED 로 암호화된 문서를 웍스AI 에 올리면, 회사가 열어도 된다고 고른 보안 등급일 때만 회사 안에서 풀어 AI 가 읽게 합니다. AI 가 만든 파일을 내려받을 때는 회사가 정한 파수 보안 등급으로 암호화해 내려보낼 수 있습니다.

웍스AI 에 문서 업로드
   → MCP Hub (지나가기만 함, 저장 안 함)
   → 회사 안의 커넥터
   → 같은 서버의 파수 사이드카가 보안 등급을 확인하고 풀어 줌
   → 풀린 문서를 웍스AI 로 돌려보냄

• 문서는 회사 전체 권한으로 엽니다. 파수 문서에 적힌 사람별 권한(누가 열 수 있는지)은 보지 않고, 보안 등급으로만 엽니다. 어떤 등급까지 AI 에 올려도 되는지는 회사 보안 담당자와 정해 주세요.
• 파수 라이브러리와 인증서(fsdinit)는 회사 서버의 사이드카에만 둡니다. MCP Hub 와 Studio 는 이 파일을 받지도, 저장하지도 않습니다.
• 풀린 문서는 사이드카의 디스크에 남지 않습니다. 작업 폴더를 메모리에만 두고, 응답을 보낸 직후 지웁니다.
• MCP Hub 에는 문서 내용과 파일 이름이 저장되지 않습니다. 사용 기록에는 시각 · 사용자 · 작업 종류(열기 · 암호화) · 보호 여부 · 형식 · 크기 · 보안 등급 · 결과 · 처리 시간 · 실패 원인 코드, 그리고 같은 문서인지 가려내는 암호화된 문서의 지문(SHA-256)이 남습니다.
• 풀린 문서를 웍스AI 가 얼마나 보관하는지는 웍스AI 의 업로드 문서 보관 정책을 따릅니다.

준비물

파수에 요청하실 것

파수 담당자(또는 파수 엔지니어)에게 아래 세 가지를 요청해 주세요. 셋 다 회사가 파수와 맺은 계약으로 받는 것이라, 저희가 대신 받거나 드릴 수 없습니다.

요청하실 때 아래 문장을 그대로 쓰셔도 됩니다.

사내 AI 서비스(웍스AI)에서 파수 FED 문서를 열고 암호화하려고 합니다. 사내 Linux 서버(x86_64, Docker)에서 FED5 Packager API(Java)를 쓰려고 하니, ① Linux x86_64 용 Packager 라이브러리(jar · .so) ② 이 연동에 쓸 서버 ID ③ 그 서버 ID 의 fsdinit 폴더(conf 의 .conf · 인증서 포함)를 준비해 주세요. 또 이 사용이 현재 라이선스 범위 안인지, 라이브러리가 파수 서버에 접속해야 하는지 알려 주세요.

fsdinit 에는 인증서와 개인 키가 들어 있습니다. 회사 보안 정책에 따라 다루시고, 커넥터 서버에서도 관리자만 읽을 수 있게 두세요 — 설치 스크립트가 맞춰 두고, 직접 설치는 A-2 입니다.

네트워크 · 방화벽

커넥터와 사이드카는 밖에서 들어오는 연결을 받지 않습니다. 사이드카 포트(8080)는 서버 밖으로 열지 않습니다. 사이드카가 만드는 코드는 밖으로 연결하지 않고, 파수 라이브러리를 서버 안에서 불러 문서를 풀고 암호화합니다. 파수 라이브러리가 회사 파수 서버에 접속해야 하는 구성인지는 파수에 확인해 주세요 — 그렇다면 커넥터 서버에서 그 서버로 나가는 길을 열어 주셔야 합니다. 커넥터의 나가는 길은 설치 가이드와 같습니다.

1. 파수 파일 놓기

파수에서 받은 라이브러리와 fsdinit 폴더를 커넥터 서버의 정해진 폴더에 둡니다. 설치 방법(스크립트 · 직접)과 상관없이 먼저 해 주세요.

sudo mkdir -p /opt/mcp-hub/fasoo/lib /opt/mcp-hub/fasoo/fsdinit
# 파수에서 받은 jar · .so 파일을 lib 에
sudo cp <받은 라이브러리 폴더>/* /opt/mcp-hub/fasoo/lib/
# fsdinit 폴더를 통째로 — 안에 conf 폴더가 바로 보여야 합니다
sudo cp -r <받은 fsdinit 폴더>/. /opt/mcp-hub/fasoo/fsdinit/
ls /opt/mcp-hub/fasoo/fsdinit/conf      # <서버 ID>.conf 와 인증서 · 키 파일이 보여야 합니다

• fsdinit/fsdinit/conf 처럼 한 겹 더 들어가 있으면 사이드카가 찾지 못합니다. fsdinit 바로 아래에 conf 가 있어야 합니다.

2. 사이드카 설치 — 설치 스크립트

저희가 보내 드린 세 파일 drm-fasoo-<버전>.tar.gz · drm-fasoo-<버전>.tar.gz.sha256 · install-drm-fasoo.sh 를 커넥터 서버의 한 폴더에 두고, 그 폴더에서 실행합니다. 설치 스크립트는 Studio 문서 보안 화면의 안내 상자에서 받으셔도 됩니다.

cd <세 파일을 둔 폴더>
sudo bash install-drm-fasoo.sh

묻는 것은 두 가지입니다.

스크립트가 하는 일 — 바꾸기 전에 할 일을 보여 드리고 y 를 받은 뒤 진행합니다.

1. 받은 파일의 확인 값(sha256)과 1장의 파수 파일 · 서버 ID 설정 파일을 확인합니다. 틀린 곳이 있으면 고칠 곳을 알려 드리고 아무것도 바꾸지 않습니다.
2. 사이드카 이미지를 올리고 설정 파일 /etc/mcp-hub/drm-fasoo.env 를 만듭니다(관리자만 읽기). 커넥터와 사이드카가 서로 확인할 토큰은 스크립트가 만듭니다.
3. 사이드카를 실행하고, 커넥터를 같은 docker 네트워크에 연결합니다. 사이드카 포트는 서버 밖으로 열지 않습니다.
4. 커넥터 secrets 폴더의 drm.env 에 DRM_FASOO_TOKEN 을 넣고 커넥터를 다시 시작합니다(몇 초 동안 웍스AI 요청이 끊깁니다). 이 파일의 다른 줄은 건드리지 않습니다.
5. 커넥터에서 사이드카에 닿는지 확인하고 끝냅니다.

• 커넥터가 둘 이상인 서버에서는 --connector <커넥터 컨테이너 이름> 을 붙여 주세요.
• 커넥터는 실행 중인 컨테이너 중 커넥터 이미지(ghcr.io/chain-partners/mcp-hub-connector)로 찾고, secrets 폴더는 그 컨테이너의 /var/secrets 연결에서 읽습니다. 찾지 못하면 부록 A 의 직접 설치를 따라 주세요.
• 이 스크립트는 회사 밖으로 아무것도 보내지 않습니다. 이미지가 공개 저장소에 없으므로 받은 파일을 회사 밖으로 다시 나누지 마세요.
• 기본 부서 · 동시 처리 수 같은 추가 값은 /etc/mcp-hub/drm-fasoo.env 에 넣고 스크립트를 다시 실행하면 반영됩니다 — 값의 뜻은 부록 A-3 의 표를 보세요.

3. Studio 에서 연결 만들기

1. 문서 보안 → DRM 연결 만들기
2. 파수 FED 를 고릅니다.
3. 연결 이름 을 적고, 커넥터 는 2장(또는 부록 A)에서 사이드카를 설치한 서버의 커넥터를 고릅니다.
4. 연결 만들고 키 발급 을 누르면 연결 주소와 키가 나옵니다. 키는 이때 한 번만 보입니다. 웍스AI 관리자 화면의 문서 보안 연결에 두 값을 넣어 주세요.

3-1. 연결 확인

화면 위의 연결 확인 을 누릅니다. 위에서부터 차례로 확인하고, 실패한 항목에서 멈춥니다.

실패했을 때

사이드카 설정 파일(drm-fasoo.env)을 고친 뒤에는 docker restart 로는 새 값이 반영되지 않습니다. 설치 스크립트를 다시 실행해 주세요(직접 설치는 docker rm -f drm-fasoo 뒤 A-4 의 docker run). 파수 파일(라이브러리 · fsdinit)만 바꾸셨다면 docker restart drm-fasoo 로 반영됩니다.

3-2. 열어도 되는 보안 등급 정하기

보안 등급 탭 에서 열어도 되는 범위를 정하고 저장합니다. 정하기 전에는 보호된 문서를 하나도 열지 않습니다.

• 지정한 등급만 열기 — 파수 관리자 화면의 보안 등급 코드를 한 줄에 하나씩 넣습니다. 파수는 등급 목록을 따로 알려 주지 않아 직접 넣으셔야 합니다. 문서에 적힌 등급 코드와 글자까지 같아야 엽니다.
• 보안 등급과 관계없이 모두 열기 — 등급과 상관없이 엽니다. 회사 보안 담당자의 승인을 받은 뒤 고르고, "보안 담당자의 승인을 받았습니다" 에 표시해야 저장됩니다.
• 파수로 암호화되지 않은 문서는 고른 등급과 관계없이 그대로 통과합니다.

3-3. 암호화 설정 (선택)

AI 가 만든 파일을 파수로 암호화해 내려보내려면 연결 설정 탭에서 넣습니다. 비워 두면 암호화하지 않고 그대로 내려보냅니다.

암호화를 켜기 전에 꼭 확인해 주세요. 시험 파일 하나를 AI 에게 만들어 달라고 해 내려받은 뒤, 파수 클라이언트에서 그 파일의 보안 등급이 넣으신 코드와 같은지 봅니다. 결과 등급이 넣은 코드와 다르면 MCP Hub 는 그 파일을 내려보내지 않습니다(암호화가 안 된 채 나가는 것을 막습니다). 이때 사용 기록에 오류로 남으니 저희에게 알려 주세요.

• 암호화한 문서의 원본 파일 이름 칸에는 document.<확장자> 가 기록됩니다. 업로드한 파일 이름을 파수 문서 정보에 남기지 않기 위해서입니다.
• 소유자 · 부서 이름에 한글을 쓰셨는데 다른 파수 화면에서 글자가 깨져 보이면 저희에게 알려 주세요.

3-4. 켜기

화면 위의 켜기 를 누릅니다. 이때부터 웍스AI 에서 올린 파수 문서를 엽니다.

4. 운영

시험 문서로 확인하기

켠 뒤 3-2 에서 고른 등급의 파수 문서를 하나 올려 보세요. 연결 확인은 라이브러리와 인증서까지만 확인하고, 실제 문서를 푸는 것은 이때 처음 확인됩니다.

1. 고른 등급의 문서를 올립니다 → 사용 기록에 열림
2. 고르지 않은 등급의 문서를 올립니다 → 등급 제한

1번이 등급 제한 으로 나오면 사용 기록에 보이는 그 문서의 등급 코드와 3-2 에 넣은 코드가 글자까지 같은지 확인해 주세요.

사용 기록

사용 기록 탭 에서 누가 어떤 형식의 문서를 열었는지, 왜 못 열었는지 볼 수 있습니다.

크기와 동시 처리

• 한 번에 올릴 수 있는 문서는 100MB 까지입니다 (암호화된 상태의 크기 기준).
• 사이드카는 한 번에 문서 하나씩 풉니다. 여러 사람이 동시에 올리면 차례로 처리하고, 30초 넘게 차례가 오지 않으면 처리 중인 요청이 많음 으로 끝납니다. 이런 일이 잦으면 저희에게 알려 주세요.

키

• 키를 잃어버렸거나 새 나간 것 같으면 연결 설정 탭에서 새 키 발급. 이전 키는 즉시 쓸 수 없고, 웍스AI 에 새 키를 넣기 전까지 문서를 열 수 없습니다. 연결 주소는 바뀌지 않습니다.

사이드카 업데이트

새 사이드카 버전이 나오면 담당자가 새 파일을 보내 드립니다. 받은 세 파일을 한 폴더에 두고 설치 스크립트를 다시 실행하면 됩니다.

cd <새 파일을 둔 폴더>
sudo bash install-drm-fasoo.sh

• 설정 파일 · 파수 파일 · 커넥터 설정은 그대로 두고 사이드카만 새 버전으로 바꿉니다. 다시 묻지 않고, 커넥터도 다시 시작하지 않습니다.
• 사이드카에 직접 붙여 두신 실행 옵션 중 메모리 · 작업 폴더 크기 · 프록시 · DNS(추가 호스트 포함)은 새 사이드카에 그대로 이어받습니다. 진행 전 화면에 「이어받는 실행 옵션」 으로 보여 드립니다. 그 밖의 옵션은 이어받지 않으니 다시 붙여 주세요. 프록시를 설정 파일에 넣어 두셨다면 설정 파일 값을 씁니다.
• 새 사이드카가 실행되지 않거나 90초 안에 응답하지 않으면 지금 사이드카로 되돌리고 멈춥니다.
• 사이드카를 바꾸는 몇 초 동안 올라오는 파수 문서는 열리지 않습니다. 사용이 적은 시간에 올려 주세요.
• 다 올린 뒤 Studio 문서 보안 → 연결 설정에서 연결 확인을 누르면, 사이드카 항목에 새 버전이 보입니다.
• 사이드카를 올리지 않아도 지금 버전으로 계속 쓰실 수 있습니다. 보안 수정처럼 꼭 올려야 하는 업데이트는 따로 알려 드립니다.
• 예전 이미지는 docker rmi drm-fasoo:<예전 버전> 으로 지울 수 있습니다.
• 직접 설치하신 경우는 부록 A-6 을 따라 주세요.

5. 끄기 · 정리

잠시 멈추려면 Studio 문서 보안 화면 위의 끄기. 다시 켜면 설정 그대로 이어집니다.

완전히 걷어내려면 아래 순서로 정리합니다.

1. Studio 연결 설정 탭 → 연결 지우기

2. 커넥터 서버에서 사이드카와 파수 파일을 지웁니다.

   docker rm -f drm-fasoo
   docker rmi drm-fasoo:<버전>
   docker network rm mcp-hub-drm
   sudo rm /etc/mcp-hub/drm-fasoo.env
   sudo rm -rf /opt/mcp-hub/fasoo
   

   docker network rm 이 커넥터가 아직 연결되어 있다고 실패하면 먼저 docker network disconnect mcp-hub-drm <커넥터 컨테이너 이름> 을 실행합니다. 같은 네트워크를 MIP 사이드카도 쓰고 있다면 네트워크는 지우지 마세요. 커넥터 secrets 폴더의 drm.env 에서 DRM_FASOO_TOKEN (넣으셨다면 DRM_FASOO_URL 도) 줄도 지워 주세요.

3. 파수 쪽에서 이 연동용으로 발급한 서버 ID 가 있다면 파수 담당자에게 회수를 요청해 주세요.

부록 A. 직접 설치 (설치 스크립트를 쓰지 않을 때)

설치 스크립트가 하는 일을 손으로 하는 방법입니다. 1장(파수 파일 놓기)을 마친 뒤 진행합니다.

A-1. 받은 파일 확인과 올리기

저희가 보내 드린 두 파일을 커넥터 서버의 같은 폴더에 두고 실행합니다.

# 1. 받은 파일이 저희가 만든 그대로인지 확인 — "OK" 가 나와야 합니다
sha256sum -c drm-fasoo-<버전>.tar.gz.sha256

# 2. 이미지 올리기
docker load < drm-fasoo-<버전>.tar.gz

# 3. 올라갔는지 확인 — drm-fasoo   <버전> 이 보여야 합니다
docker images drm-fasoo

• OK 가 나오지 않으면 실행하지 마세요. 파일이 전송 중에 깨졌거나 다른 파일입니다. 담당자에게 다시 요청해 주세요.
• <버전> 은 Studio 사이드카 안내 상자의 「직접 설치하기」 에 보이는 버전입니다.
• 이 이미지는 공개 저장소에 없습니다. 회사 밖으로 다시 나누지 마세요.

A-2. 파수 파일 권한

# 사이드카(사용자 번호 10001)만 읽을 수 있게
sudo chown -R 10001 /opt/mcp-hub/fasoo/lib /opt/mcp-hub/fasoo/fsdinit
sudo chmod -R go-rwx /opt/mcp-hub/fasoo/fsdinit

A-3. 설정 파일 만들기

먼저 커넥터와 사이드카가 서로 확인할 때 쓰는 긴 무작위 문자열을 만듭니다.

openssl rand -hex 32

나온 값을 FASOO_SIDECAR_TOKEN 에 넣고 파일로 저장합니다.

sudo mkdir -p /etc/mcp-hub
sudo tee /etc/mcp-hub/drm-fasoo.env > /dev/null <<'EOF'
FASOO_SERVER_ID=<파수가 발급한 서버 ID>
FASOO_SIDECAR_TOKEN=<위에서 만든 무작위 문자열>
FASOO_DEFAULT_OWNER=<암호화한 문서의 기본 소유자 파수 사용자 ID>
EOF
sudo chmod 600 /etc/mcp-hub/drm-fasoo.env

• 값에 따옴표를 붙이지 않습니다. 따옴표까지 값으로 읽힙니다.

A-4. 사이드카 실행

docker network create mcp-hub-drm   # 이미 있다고 나오면 넘어가세요
sudo docker run -d --name drm-fasoo --restart unless-stopped --network mcp-hub-drm \
  --platform linux/amd64 --memory 1g --tmpfs /work:uid=10001,size=512m \
  --env-file /etc/mcp-hub/drm-fasoo.env \
  -v /opt/mcp-hub/fasoo/lib:/opt/fasoo/lib:ro \
  -v /opt/mcp-hub/fasoo/fsdinit:/opt/fasoo/fsdinit:ro \
  drm-fasoo:<버전>
docker network connect mcp-hub-drm <커넥터 컨테이너 이름>

• --tmpfs /work — 사이드카가 문서를 푸는 작업 폴더를 메모리에만 둡니다. 풀린 문서가 서버 디스크에 한 번도 쓰이지 않습니다.
• --memory 1g · size=512m — 100MB 근처의 큰 문서를 자주 여신다면 작업 폴더(size)를 넉넉히 늘리고, --memory 는 작업 폴더 크기보다 512MB 이상 크게 잡아 주세요.
• sudo — A-3 에서 설정 파일을 관리자만 읽게 두었으므로 docker run 은 sudo 로 실행합니다.
• :ro — 파수 파일을 읽기만 합니다. 사이드카가 라이브러리나 인증서를 바꾸지 않습니다.
• docker network connect — 커넥터가 사이드카를 drm-fasoo 라는 이름으로 찾게 합니다. 커넥터 컨테이너 이름은 docker ps 로 확인하실 수 있습니다. 커넥터를 업데이트하느라 컨테이너를 새로 만들면 이 줄을 다시 실행해야 합니다 (Studio 의 커넥터 업데이트 명령에는 이미 들어 있습니다).
• 포트를 열지 않습니다. -p 8080:8080 을 붙이지 마세요.

사이드카가 떴는지 확인:

docker ps --filter name=drm-fasoo

A-5. 커넥터 설정

커넥터 secrets 파일에 사이드카 토큰을 넣고 커넥터를 다시 시작합니다.

sudo tee -a /etc/mcp-connector/secrets/drm.env > /dev/null <<'EOF'
DRM_FASOO_TOKEN=<FASOO_SIDECAR_TOKEN 과 같은 값>
EOF
sudo chmod 600 /etc/mcp-connector/secrets/drm.env
docker restart <커넥터 컨테이너 이름>

• DRM_FASOO_TOKEN 은 A-3 의 FASOO_SIDECAR_TOKEN 과 글자 하나까지 같아야 합니다.
• 사이드카 컨테이너 이름을 drm-fasoo 가 아닌 이름으로 실행하셨다면 DRM_FASOO_URL=http://<사이드카 컨테이너 이름>:8080 도 넣습니다.

A-6. 사이드카 업데이트 (직접)

새 사이드카 버전이 나오면 담당자가 새 파일을 보내 드립니다. 설정 파일(/etc/mcp-hub/drm-fasoo.env) · 파수 파일 · 커넥터 설정은 그대로 둡니다.

# 1. 새 파일 확인과 올리기 (A-1 과 같습니다)
sha256sum -c drm-fasoo-<새 버전>.tar.gz.sha256
docker load < drm-fasoo-<새 버전>.tar.gz

# 2. 지금 사이드카 지우기
docker rm -f drm-fasoo

# 3. 새 버전으로 실행 — A-4 의 docker run 명령에서 이미지 버전만 바꿉니다
sudo docker run -d --name drm-fasoo --restart unless-stopped --network mcp-hub-drm \
  --platform linux/amd64 --memory 1g --tmpfs /work:uid=10001,size=512m \
  --env-file /etc/mcp-hub/drm-fasoo.env \
  -v /opt/mcp-hub/fasoo/lib:/opt/fasoo/lib:ro \
  -v /opt/mcp-hub/fasoo/fsdinit:/opt/fasoo/fsdinit:ro \
  drm-fasoo:<새 버전>

• 2번과 3번 사이(몇 초) 동안 올라오는 파수 문서는 열리지 않습니다. 사용이 적은 시간에 올려 주세요.
• 커넥터는 다시 시작하지 않아도 됩니다.
• 다 올린 뒤 Studio 문서 보안 → 연결 설정에서 연결 확인을 누르면, 사이드카 항목에 새 버전이 보입니다.
• 사이드카를 올리지 않아도 지금 버전으로 계속 쓰실 수 있습니다. 보안 수정처럼 꼭 올려야 하는 업데이트는 따로 알려 드립니다.
• 예전 이미지는 docker rmi drm-fasoo:<예전 버전> 으로 지울 수 있습니다.