> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marketplace.bsggo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 설치 가이드

> ISMS-P Intelligence Dashboard CLI 설치, 배포, 제거 방법을 안내합니다.

## CLI 설치

`stable` 채널을 사용하면 항상 최신 안정 버전이 설치됩니다. 재실행하면 자동으로 새 버전으로 갱신됩니다.

<Tabs>
  <Tab title="macOS / Linux / AWS CloudShell">
    ```bash theme={null}
    curl -sSL https://marketplace-isms-p-intelligence-dashboard-public.s3.amazonaws.com/releases/stable/cli/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows (CMD / PowerShell)">
    ```cmd theme={null}
    powershell -c "irm https://marketplace-isms-p-intelligence-dashboard-public.s3.amazonaws.com/releases/stable/cli/install.ps1 | iex"
    ```
  </Tab>
</Tabs>

<Tip>
  AWS CloudShell을 사용하면 AWS 인증이 자동 설정되어 가장 간편합니다.
  AWS 콘솔 검색창 옆 `>_` 아이콘을 클릭하여 CloudShell을 열 수 있습니다.
</Tip>

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-install.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=00d35e8e9de8a7ec80b76bca9e75d9ab" alt="CLI 설치" width="1238" height="368" data-path="isms-p-dashboard/images/cli-install.png" />
</Frame>

## 지원 리전

현재 **ap-northeast-2 (서울)** 리전만 지원합니다.

***

## 사전 요구사항

시작하기 전에 아래 네 가지를 준비하세요.

### 1. AWS Marketplace 구독

AWS Marketplace에서 제품을 구독해야 합니다.
구독이 없으면 설치 시 "구독이 확인되지 않았습니다" 에러가 발생합니다.

구독 문의: [mp\_support@bsgglobal.com](mailto:mp_support@bsgglobal.com)

### 2. AWS 인증

배포 대상 AWS 계정에 **AdministratorAccess** 권한으로 인증되어 있어야 합니다.

```bash theme={null}
aws configure
# 또는
aws sso login --profile <profile>
```

CloudShell에서는 이미 인증되어 있으므로 이 단계를 건너뜁니다.

<Tip>
  AWS 프로필이 여러 개인 경우, 설치 시 프로필을 선택할 수 있습니다.
  선택한 프로필은 저장되어 이후 명령어에서 자동으로 사용됩니다.
  `--profile` 플래그로 임시 변경도 가능합니다.
</Tip>

### 3. Terraform Cloud 토큰

[app.terraform.io](https://app.terraform.io)에서 API 토큰을 발급받으세요.

| 토큰 유형             | 발급 경로                                   | 비고                   |
| ----------------- | --------------------------------------- | -------------------- |
| User API Token    | User Settings > Tokens                  | 개인 사용자 권한 상속         |
| Team API Token    | Organization Settings > Teams > 해당 Team | 팀 워크스페이스 권한 필요       |
| `terraform login` | 터미널에서 `terraform login` 실행              | User API Token 자동 발급 |

<Warning>
  Organization Token은 run 생성 권한이 없어 사용할 수 없습니다.
</Warning>

설치 시 `terraform login` 토큰이 감지되면, 해당 토큰을 사용할지 직접 입력할지 선택할 수 있습니다.

### 4. 스캔 대상 계정 Credential

스캔할 AWS 계정마다 **IAM Access Key**가 필요합니다. 설치 과정에서 입력합니다.

**대상 계정에서 사전 준비:**

1. IAM 콘솔에서 사용자를 생성합니다
2. **IAMFullAccess** 정책을 연결합니다 (ScanRole 자동 생성에 필요)
3. Access Key를 발급받아 메모해둡니다

<Info>
  ScanRole(읽기 전용)이 자동 생성된 후에는 Access Key 대신 ScanRole로 스캔합니다.
  Access Key는 최초 ScanRole 생성에만 사용되므로, ScanRole 생성 완료 후 IAM 사용자를 삭제해도 됩니다.
</Info>

***

## 빠른 시작

### Step 1. 설치

```bash theme={null}
isms-p install
```

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-install-profile.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=c6689c32108957cfac873a34c8cd8c4c" alt="프로필 선택" width="1238" height="319" data-path="isms-p-dashboard/images/cli-install-profile.png" />
</Frame>

화면 안내에 따라 아래 정보를 입력합니다:

| 입력 항목            | 설명                                | 예시                          |
| ---------------- | --------------------------------- | --------------------------- |
| TFC API Token    | 위에서 발급한 토큰 (마스킹 표시)               | `bmJzy...`                  |
| TFC Organization | Terraform Cloud 조직 이름             | `my-company`                |
| TFC Project      | 프로젝트 이름 (Enter = Default Project) | `isms-p`                    |
| 관리자 이메일          | 스캔 실패 알림 + QuickSight 계정          | `admin@company.com`         |
| 스캔 대상 계정 ID      | 스캔할 AWS 계정 (comma로 구분)            | `111111111111,222222222222` |

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-install-config.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=8769c3102bb401b6f920e1525d7f1e62" alt="설정 입력" width="1238" height="587" data-path="isms-p-dashboard/images/cli-install-config.png" />
</Frame>

입력값을 확인한 후 진행 여부를 선택합니다. 확인 후 자동으로 인프라 배포가 시작됩니다. 약 10\~15분 소요됩니다.

**배포 과정 (자동):**

1. CloudFormation 스택 생성 (Bootstrap 인프라)
2. Bootstrap 실행 (OIDC Provider, TFC Run Role, S3 버킷, QuickSight 구독 자동 생성)
3. Bootstrap 완료 후 임시 리소스(EC2, VPC 등) 자동 정리
4. Terraform Cloud workspace 생성 확인
5. Terraform Apply (Lambda, Step Functions, Glue, Athena, QuickSight 대시보드 등 42개 리소스)

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-install-deploy.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=21ba9752827aeff4d8ce3174375e4afa" alt="배포 진행" width="1238" height="685" data-path="isms-p-dashboard/images/cli-install-deploy.png" />
</Frame>

### Step 2. Credential 입력

배포 완료 후 각 대상 계정의 **IAM Access Key**를 입력합니다.

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-install-credential.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=fd1a48426d2305e40ffe3b13d9362d22" alt="Credential 입력" width="1238" height="587" data-path="isms-p-dashboard/images/cli-install-credential.png" />
</Frame>

<Info>
  Credential 설정이 완료되면 Apply가 진행되고, 스캔 실행 여부를 물어봅니다.
  설치 중 Credential 입력을 건너뛰면 나중에 `isms-p target auth <account_id>`로 설정할 수 있습니다.
  Credential이 설정되지 않은 계정은 스캔이 실행되지 않습니다.
</Info>

### Step 3. 설치 완료

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-install-complete.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=edf286613cde43bfdf16190e53abec62" alt="설치 완료" width="1238" height="319" data-path="isms-p-dashboard/images/cli-install-complete.png" />
</Frame>

설치가 완료되면 다음이 자동으로 처리됩니다:

* **QuickSight Admin 자동 등록**: 설치를 실행한 AWS IAM 사용자/역할이 QuickSight ADMIN으로 자동 등록됩니다. 별도의 QuickSight 사용자 설정이 필요 없습니다.
* **대시보드 URL 안내**: 설치 완료 메시지에 QuickSight 대시보드 URL과 **포털(뷰어 SPA) URL**이 함께 표시됩니다.
* **관리자 콘솔 자동 활성화**: 설치 시 입력한 관리자 이메일이 Cognito **admin** 그룹에 자동으로 등록되어, 포털 로그인 후 관리자 콘솔(`/admin`)에 접근할 수 있습니다.

#### 접근 경로 두 가지

| 경로                                          | 대상                  | 인증                           | 용도                      |
| ------------------------------------------- | ------------------- | ---------------------------- | ----------------------- |
| **QuickSight 대시보드 URL**                     | AWS 콘솔 접근 권한 보유자    | AWS IAM                      | QuickSight 콘솔에서 직접 열람   |
| **포털 URL** (`https://xxxxx.cloudfront.net`) | 모든 열람자 (AWS 권한 불필요) | Cognito (이메일/비밀번호, Google 등) | 뷰어로 대시보드 열람 + 관리자 콘솔 접근 |

<Tip>
  **QuickSight 대시보드 접속 방법:**

  1. 설치 완료 시 표시된 URL을 브라우저에서 엽니다
  2. AWS 콘솔에 로그인된 상태에서 접속해야 합니다 (설치 시 사용한 계정)
  3. 첫 스캔이 완료되어야 데이터가 표시됩니다 (스캔 소요 시간: 약 10\~30분)

  URL을 잊어버린 경우 `isms-p status`로 다시 확인할 수 있습니다.
</Tip>

<Tip>
  **포털 / 관리자 콘솔 접속 방법:**

  1. 설치 완료 후, 입력한 관리자 이메일로 **"ISMS-P Intelligence Dashboard 뷰어 접속 초대"** 메일이 자동 발송됩니다 (메일 미수신 시 스팸함 확인).
  2. 메일에 포함된 **임시 비밀번호**와 이메일 주소로 포털 URL(`https://xxxxx.cloudfront.net`)에 로그인합니다.
  3. 최초 로그인 시 비밀번호를 변경합니다.
  4. 로그인 후 헤더 우측의 **"관리자"** 링크를 클릭하면 관리자 콘솔(`/admin`)로 이동합니다.

  관리자 콘솔에서 브랜딩, 인증 설정, 사용자, 라이센스, 커스텀 도메인을 관리할 수 있습니다.
  자세한 내용은 [설정 가이드 > 관리자 콘솔](/isms-p-dashboard/settings/admin-console)을 참조하세요.
</Tip>

<Accordion title="다른 사용자에게 대시보드 공유">
  * **포털 (권장)**: 추가 사용자가 포털에 직접 가입하면 자동으로 뷰어 그룹에 할당됩니다 (허용 도메인 설정 시 그 도메인 이메일만 가능). AWS 권한이 필요 없습니다.
  * **QuickSight 콘솔 직접 접속**: AWS QuickSight 콘솔에서 사용자를 초대하고 대시보드에 권한을 부여합니다.
    1. AWS 콘솔 > QuickSight > 사용자 관리
    2. 사용자 초대 (이메일 주소 입력)
    3. 대시보드에서 공유 설정
</Accordion>

### Step 4. 상태 확인

```bash theme={null}
isms-p status
```

배포 상태, 대상 계정 수, 최근 스캔 결과, 대시보드 URL을 확인합니다.

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-status.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=2ba1632457a70eac42c24e12fa83f88b" alt="상태 확인" width="1238" height="294" data-path="isms-p-dashboard/images/cli-status.png" />
</Frame>

***

## 업데이트

업데이트는 두 가지 경로로 처리됩니다.

| 구분    | 변경 대상                                            | 사용자 작업                                |
| ----- | ------------------------------------------------ | ------------------------------------- |
| 자동 반영 | 스캔 로직(Lambda 이미지), Terraform 모듈, IAM 정책, 대시보드 정의 | 없음                                    |
| 재설치   | Bootstrap / CloudFormation 템플릿이 변경된 메이저 업데이트     | 최신 CLI 다운로드 → `uninstall` → `install` |

### 1. 자동 반영 (사용자 작업 불필요)

설치된 환경은 제품 릴리스 채널(Stable)을 추적합니다.
신규 버전이 릴리스되면 다음 항목이 **다음 자동 apply 시 고객 환경에 자동으로 반영**됩니다.

* 스캔 로직 (Lambda 컨테이너 이미지)
* Terraform 모듈 (Step Functions, Glue, Athena, QuickSight 등)
* TFC Run Role IAM 정책 (core / analytics)
* 대시보드 정의 (QuickSight)

신규 릴리스가 vendor 레포(`release/stable`)에 push되는 시점에 Terraform Cloud가 자동으로 plan/apply를 실행합니다.

<Info>
  자동 반영을 즉시 트리거하고 싶을 때는 Terraform Cloud 콘솔에서 해당 workspace의 **Actions > Start new run**을 실행하면 됩니다.
</Info>

### 2. 재설치 (Bootstrap 변경 시)

Bootstrap(CloudFormation 템플릿, OIDC/Role 구성, TFC 변수 스키마 등)이 변경된 메이저 업데이트는 자동 반영되지 않으며, **최신 CLI를 다운로드한 뒤 기존 환경을 제거하고 새로 설치해야 합니다.**

**Step 1.** 최신 CLI 다운로드 — 위 [CLI 설치](#cli-설치) 명령어를 다시 실행하면 새 버전으로 갱신됩니다.

**Step 2.** 제거 후 재설치

```bash theme={null}
isms-p uninstall
isms-p install
```

또는 `isms-p install`만 실행해도 기존 설치를 자동으로 감지하여 **"제거 후 재설치"** 옵션을 제공합니다.

<Info>
  재설치 시 설정 파일(`~/.isms-p-dashboard/config.yaml`)은 보존되어 이전 입력값(TFC 조직, 관리자 이메일, 대상 계정 등)을 재사용할 수 있습니다.
</Info>

<Warning>
  **과거 스캔 데이터는 자동으로 이어지지 않습니다.**

  재설치 시 새로운 S3 Data Lake 버킷이 생성됩니다. 기존 버킷을 남겨두더라도 자동으로 연결되지 않으므로,
  과거 스캔 이력을 유지하려면 기존 버킷의 데이터를 새 버킷으로 직접 복사해야 합니다 (`aws s3 sync` 등).

  데이터 마이그레이션이 필요하면 [mp\_support@bsgglobal.com](mailto:mp_support@bsgglobal.com)으로 문의하세요.
</Warning>

<Info>
  **재설치가 필요한지 어떻게 알 수 있나요?**

  현재 자동 고지 채널은 운영되지 않고 있습니다. 재설치 필요 여부가 의심되면 [mp\_support@bsgglobal.com](mailto:mp_support@bsgglobal.com)으로 문의하세요.
</Info>

***

## 제거

더 이상 사용하지 않을 때 전체 인프라를 제거합니다.

```bash theme={null}
isms-p uninstall
```

<Frame>
  <img src="https://mintcdn.com/bsgpartners/zu001z7Vrz1OoUG1/isms-p-dashboard/images/cli-uninstall.png?fit=max&auto=format&n=zu001z7Vrz1OoUG1&q=85&s=15b127765ca4a95a4c21b6220568f224" alt="제거" width="1238" height="782" data-path="isms-p-dashboard/images/cli-uninstall.png" />
</Frame>

순서대로 진행됩니다:

1. **Terraform destroy** — Lambda, Step Functions, Glue, Athena, QuickSight 대시보드 등 모든 Terraform 리소스 삭제
2. **TFC Workspace 삭제**
3. **Bootstrap 리소스 정리** — TFC Run Role, Bootstrap Role, OIDC Provider
4. **S3 Data Lake 삭제 여부 확인** (스캔 이력 데이터)
5. **QuickSight 구독 해지 여부 확인** (월정액)

<Accordion title="S3와 QuickSight는 왜 선택인가요?">
  * **S3 Data Lake**: 과거 스캔 이력은 감사 증적/컴플라이언스 증빙으로 가치가 있을 수 있습니다. 삭제하면 복구할 수 없습니다.
  * **QuickSight 구독**: 월정액 과금(Enterprise \$18/user/month)이 발생하지만, 다른 용도로 이미 사용 중일 수 있어 고객 판단에 맡깁니다.
</Accordion>

<Accordion title="재설치해도 문제없나요?">
  `isms-p uninstall` 후 `isms-p install`로 재설치할 수 있습니다.
  설정 파일(`~/.isms-p-dashboard/config.yaml`)은 보존되어 이전 설정을 재사용할 수 있습니다.

  * **S3 Data Lake**: 재설치 시 항상 새 버킷이 생성됩니다. 기존 버킷을 남겨두어도 자동으로 연결되지 않으므로, 과거 데이터를 유지하려면 새 버킷으로 직접 복사해야 합니다.
  * **QuickSight 구독을 남겨둔 경우**: 기존 구독을 사용하여 대시보드만 재생성합니다.
  * **QuickSight 구독을 해지한 경우**: 구독부터 새로 생성합니다.
</Accordion>

확인 없이 전부 삭제하려면:

```bash theme={null}
isms-p uninstall --all
```

<Accordion title="CLI 없이 콘솔에서 제거하는 경우">
  TFC 콘솔과 AWS 콘솔에서 직접 제거할 수도 있습니다.

  **1단계: Terraform destroy (TFC 콘솔)**

  1. [app.terraform.io](https://app.terraform.io)에 로그인
  2. 해당 workspace의 Settings > Destruction and Deletion
  3. "Queue destroy plan" 실행
  4. Plan 확인 후 Apply

  **2단계: TFC Workspace 삭제 (TFC 콘솔)**

  1. 같은 Settings > Destruction and Deletion
  2. "Delete from HCP Terraform" 실행

  **3단계: Bootstrap 리소스 수동 정리 (AWS 콘솔)**

  | 리소스            | 콘솔 경로                    | 삭제 대상                                                                    |
  | -------------- | ------------------------ | ------------------------------------------------------------------------ |
  | TFC Run Role   | IAM > Roles              | `isms-p-intelligence-dashboard-tfc-run`                                  |
  | TFC Run Policy | IAM > Policies           | `...-tfc-run-policy-core`, `...-analytics`                               |
  | Bootstrap Role | IAM > Roles              | `Product` 태그가 `isms-p-intelligence-dashboard`인 role 중 이름에 `bootstrap` 포함 |
  | OIDC Provider  | IAM > Identity providers | `app.terraform.io`                                                       |

  <Info>
    Bootstrap 리소스를 삭제하지 않아도 재설치에 문제는 없습니다.
    CLI는 재설치 시 잔류 Bootstrap 리소스를 자동으로 감지하고 정리한 후 진행합니다.
  </Info>

  **4단계: S3 / QuickSight (선택)**

  | 리소스           | 콘솔 경로                 | 삭제 방법                                                                           |
  | ------------- | --------------------- | ------------------------------------------------------------------------------- |
  | S3 Data Lake  | S3 콘솔                 | `isms-p-intelligence-dashboard-data-`로 시작하는 버킷. 버전 관리가 활성화되어 있으므로 "버킷 비우기" 후 삭제 |
  | QuickSight 구독 | QuickSight 콘솔 > 계정 관리 | 종료 보호 해제 후 구독 삭제                                                                |
</Accordion>

***

## 명령어 요약

| 명령어                         | 설명                        |
| --------------------------- | ------------------------- |
| `isms-p install`            | 설치 (설정 + 배포 + credential) |
| `isms-p status`             | 상태 확인 (배포, 스캔, 대시보드 URL)  |
| `isms-p uninstall`          | 제거                        |
|                             |                           |
| `isms-p config`             | 설정 확인/변경                  |
| `isms-p config --edit`      | 인터랙티브 설정 편집               |
|                             |                           |
| `isms-p target list`        | 스캔 대상 목록                  |
| `isms-p target add [id]`    | 대상 추가 + credential        |
| `isms-p target auth [id]`   | credential 설정/변경          |
| `isms-p target remove [id]` | 대상 제거                     |
|                             |                           |
| `isms-p scan`               | 수동 스캔 실행                  |
| `isms-p version`            | 버전 정보                     |