English · 한국어

pqcota 데모(OSS): 접근 준비 → 관측 → 인벤토리 → 전환물 생성¶

Docker만 있으면 한 줄로 설치하고, 실행하고, 스스로 지우는 종단 데모입니다. 가상 네트워크 하나에 묶인 노드들에서 pqcota가 전체 범위를 보여 줍니다. ① 사용자의 hosts 파일로 접근 준비 → ② Ansible/SSH로 OpenSSL, Java(JCA), 통신 핸드셰이크 관측 → ③ 중앙 인벤토리 → ④ 전환물 생성(플레이북 생성 → 적용 → 되돌림)입니다.

이 문서는 데모를 돌리는 사람을 위한 것입니다. 연결된 문서 중 한국어판이 없는 것은 영문입니다.

📊 실행하기 전에 볼 기대 결과: expected-output/에 콘솔 출력 샘플과 토폴로지 SVG가 있고, 실제 실행에서 달라질 수 있는 것(엣지 캡처 시점, 베이스 이미지 버전)도 적혀 있습니다.

요구 사항¶

• Docker(Compose v2), 인터넷(처음 이미지를 빌드할 때), docker 그룹에 속한 사용자(root나 KVM은 필요 없음)
• 다섯 리포를 나란히 클론해 둘 것(이 리포의 디렉터리 이름은 pqcota이고, 그 옆에 pqcota-common, pqcota-inventory, pqcota-discovery, pqcota-provisioning을 둡니다). 데모 이미지가 모두 빌드합니다. 빌드 안내를 보세요.

리포는 pqcota-ctl 컨테이너 안에서 빌드합니다. 빌드되는 것은 지금 체크아웃한 소스 그대로이며 커밋하지 않은 변경도 포함합니다.

빠른 시작¶

./demo/scripts/up.sh      # images → containers → build the repo on ctl → SSH keys → hosts.csv
./demo/scripts/demo.sh    # access prep → discovery → inventory → provisioning (generate, apply, roll back)
./demo/scripts/down.sh    # clean up (--rmi also removes images)

./demo/scripts/demo.sh --help는 조절할 수 있는 항목을 모두 보여 줍니다. 그중 하나가 아래의 선택 단계입니다.

처음이라면 scripts/의 이 스크립트 세 개면 충분합니다. 다른 폴더는 그 뒤에서 도는 장치입니다.

데모 환경은 파일 하나, demo/topology/topology.yaml로 정의됩니다. 처음 실행하면 샘플이 자동으로 복사됩니다(git은 무시합니다). 이 파일을 고치면 노드 수, 노드 종류, OpenSSL 버전, JCA provider, 네트워크 구간, 핸드셰이크가 모두 따라 바뀝니다. 그러니 사용자 환경에 더 가깝게 만들어 같은 종단 흐름을 돌려 볼 수 있습니다. 자세한 내용: topology/README(영문).

무엇이 보이나¶

demo.sh는 진행 상황을 ▶ N/6으로 보고합니다. 기본 토폴로지에는 노드가 셋 있고(web-gw(OpenSSL 3.x), pay-app(JVM), pay-db(OpenSSL 1.1.1, 레거시)), 컨트롤러 pqcota-ctl이 SSH로 이 노드들을 스캔합니다. 단계마다 보이는 것은 다음과 같습니다.

출력에 그대로 나오지만 오류가 아닌 것이 둘 있습니다. - ⚠ duplicate: physical machine … → [pay-db web-gw]: Linux 호스트에서 나타납니다. 데모의 대상은 한 호스트의 컨테이너이고, Linux에서는 컨테이너 안에서 호스트의 머신 지문이 보여서 셋의 값이 같습니다. 한 머신을 여러 이름으로 등록했을 때 운영에서 보게 되는 것과 같습니다. Mac의 Docker Desktop에서는 지문이 다른 곳에서 오므로 이 줄이 나타나지 않습니다(까닭). - 전환물 생성이 놓는 oqsprovider.so는 빈 파일입니다. 데모가 보이는 것은 배포와 되돌릴 수 있음이지 암호 능력이 아닙니다(까닭). 실물로 확인하려면 아래 선택 단계를 켜세요.

선택 단계: 실물 provider로 마지막 한 걸음(DEMO_REAL_PROVIDER=1)¶

DEMO_REAL_PROVIDER=1 ./demo/scripts/demo.sh

빈 파일로는 보일 수 없는 것이 하나 있습니다. 도구가 만든 설정과 배치가 실제로 암호 능력을 만드는가입니다. 이 변수를 켜면 노드와 같은 베이스 위에서 실물 oqsprovider(liboqs와 oqs-provider)를 빌드해 그 마지막 한 걸음을 확인합니다. 처음 실행에는 빌드에 몇 분이 걸리고, 그 뒤로는 이미지를 재사용합니다.

대상은 pay-db가 아니라 인벤토리에서 OpenSSL 3.0–3.4로 관측된 노드입니다. provider는 OpenSSL 3의 개념이라 1.1.1 노드에는 놓을 곳이 없습니다. 같은 L2/L3 산출물이 그것을 배치하고 활성화한 다음 이렇게 됩니다.

다시 관측해도 인벤토리는 바뀌지 않습니다. 오류가 아닙니다. OpenSSL에는 아직 provider 계층을 관측할 경로가 없고, 데모가 그 까닭을 함께 출력합니다.

출력이 놓이는 곳¶

대부분은 컨테이너 안에 있고, 리포에 놓이는 것은 demo/.generated/(git은 무시)뿐입니다. down.sh는 그 폴더를 통째로 지우고, 컨테이너 안에 있는 것은 컨테이너와 함께 사라집니다.

안을 들여다보려면(데모를 내리기 전에):

docker exec pqcota-ctl ls -R /work           # everything on the controller
docker exec pqcota-ctl cat /work/ansible/provision.yml   # the generated playbook
docker exec pqcota-demo-pg psql -U postgres -d pqcota -c '\dt'  # the inventory tables

호스트 파일 시스템은 거의 건드리지 않습니다. 리포에 남는 것은 위의 그림과 생성 파일뿐이고, 그것들도 git이 무시합니다. 접속 키(/work/id_demo)와 targets.ini는 컨트롤러 안에만 있으며 인벤토리로 적재되지 않습니다.

사용자의 환경(실제 자산)에 적용하려면¶

데모는 컨테이너를 대신 띄워 줍니다. 실제 자산에서는 환경이 이미 있으므로 세 가지를 준비합니다. 머신의 역할은 데모와 같습니다. pqcota-ctl은 리포를 클론해 빌드하는 머신이고, 노드에는 미리 설치된 것이 없습니다. hosts.csv로 끝나지 않습니다.

그 뒤는 데모와 같습니다. 수집한 결과를 pqcota-ingest에 넘기면 정규화해 저장하고, pqcota-inventory로 봅니다.

✅ 데모의 수집기 배포를 그대로 복사해도 됩니다. 노드 이미지에는 수집기가 없고, discover.yml이 ctl에서 배포하고, 실행하고, 결과를 가져오고, 정리합니다(실행이 끝나면 /tmp의 작은 Java 파일을 빼고 노드에는 자기 것이 남지 않습니다). JVM 추가 구성요소는 -recon으로 JVM이 있는 노드에만 갑니다. 실제 환경으로 옮기려면 collector_bin_dir이 사용자의 빌드 산출물(아키텍처별)을 가리키게 하기만 하면 됩니다.

실환경으로 가져가지 않을 데모 전용 요소: - 트래픽 생성(groups.ini의 traffic=, pqcota-gen-traffic.sh): 데모에는 관측할 핸드셰이크가 없어서 일부러 만들어 냅니다. 실제 환경에는 실제 트래픽이 있으므로 pqcota-netcap <node> <iface> <window>로 관측하기만 하면 됩니다.

선택: 노드 등록 관문(pqcota-ingest <dir> <scope-file>), 자산 범위(-scope-assets), CMDB 프로파일(pqcota-profile), Postgres 저장(PQCOTA_DSN), 서명 검증(PQCOTA_VERIFY_KEY). 무엇이 필수이고 무엇이 선택인지는 pqcota-discovery cmd README(영문)를 보세요.

관측 너머¶

관측은 「실제로 협상된 것」(등급)까지 보여 줍니다. 「그것이 선언된 것과 얼마나 맞는가(CONFIRMED/UNDECLARED/UNOBSERVED)」와 거버넌스, 대조는 이 리포가 하지 않으므로 데모에도 없습니다.