Release notes: 0.7.1
- Updated depedencies and report text outputs 
Release notes: 0.7
- Uses beta endpoint now by default, --expand option now expands the results to report regardless of the use of --allTerminations
Release notes: 0.6.9
- using --expand=9c06d103-f5b0-4404-bb25-aec4636912cd,47087cd3-64e9-470b-980a-5662f498e016 and expand 10 group members to for separate inspection.
Release notes: 0.6.8
- When you update policy with any guest conditions in GUI that policy will be only available from the beta endpoint after the update (during preview). 
- This update brings normalization for policies that are transfered to beta endpoint due to this behavior. 
- The policy will be evaluated like the previous guest conditions, as long as the following conditions are included "internalGuest,b2bCollaborationGuest,b2bCollaborationMember" and no tenants are excluded from the policy. In order to evaluate transferred policies, 
- use '--allowPreviewPolicies' when running CaOptics to account for this behavior

Release notes: 0.6.6-7 beta
- Allow use of different login endpoints for login and graph with params: --altLogin --altGraph
- Allow use of custom filtering for policies (this only recommended, when the policies do not adhere to expected schema)

Release notes: 0.6.5 beta
- Added counter to reporting when high number of permutations is also added to report (default is to add only unterminated)
- Minor code fixes changing <var> to <let> 
- Report filename now includes day, month, year and tenantId e.g. report_day_4_month_9_year_2022-tenant_48f55450-183a-45d6-a9ce-68f3cbc68947.csv

Release notes: 0.6.4 beta
- Get more groups per single call (less batching)
- Fix race condition detected when generally using for await loops 
- Enclose values with "" between delimitters (CSV)

Release notes: 0.6.3 beta
- Optimizations to way the mapped objects are handled. 
  - Mapped objects are cached. You can recreate the object mapping by using parama 'clearMappingCache'
  - Lookup keys will start from 'user/group/role' conditions always first
  - Added possibility to populate usermap with random UUID's to test for performance impact (this just debug option, and not really something that would be in non-beta versions)

Release notes: 0.6.2 beta
- Separated cache params into separate functions -> (clearTokenCache and ClearPolicyCache)
- Added possibility of running pre-optimized algorithm on permutations with param --aggressive (High memory consumption, only here for A/B testing)
- merge completed.

Release notes: 0.6.1 beta 
- Basic version of CSV reporting added
- Streamlined permutation generation to ensure essential permutations are generated, and some permutations are are terminated earlier on the lookups

Release notes: 0.6 beta (first non "silent" release)
- App displayNames added to MD report. Object type added to the user type

Release notes: 0.5.2,0.5.1,0.5 beta  (see previous branches for release notes)

**Azure Cloud Shell (Bash) 用のファイア・アンド・フォーゲット実行セットアップ**```bash
curl -o- https://raw.githubusercontent.com/jsa2/caOptics/main/init.sh | bash;
# Force reload of NVM
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" 
# This loads nvm

**Azure AD 関連**
- Azure AD Security Reader ロールが有効になっている 
- Azure CLI と既存の CLI セッションがある場合、このツールはその [セッション](https://github.com/jsa2/caoptics/blob/main/tokenHandler/getCode.js) を使用します。 
   - Azure CLI がインストールされていない場合は、Azure CLI の clientID だけが、Node.js http クライアントによって開始される device_code フローでトークンを取得するために使用されます。

      >![](https://assets.kitploit.com/production/public/readmes/47865/74e5e9fa7f505e20aecbe9ab86620b749fbecbd246cf233c4826991cda9a493b.png)  


**以下のオープンソースパッケージが使用されています**

コード量を減らすために、操作と美観のために以下の依存関係を使用しています（これらの素晴らしいパッケージのメンテナーの皆様に敬意を表します。各パッケージのライセンスリンクはライセンス列に記載されています）。
  
  パッケージ | 見た目|操作|ライセンス
  -|-|-|-
  [axios](https://www.npmjs.com/package/axios)||✅ | [MIT](https://github.com/axios/axios/blob/v1.x/LICENSE)
  [yargs](https://www.npmjs.com/package/yargs)||✅ | [MIT](https://github.com/yargs/yargs/blob/main/LICENSE)
  [jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken) | |✅|[MIT](https://github.com/auth0/node-jsonwebtoken/blob/master/LICENSE)
  [chalk](https://www.npmjs.com/package/chalk)| ✅ | |[MIT](https://github.com/chalk/chalk/blob/main/license)
   [js-beautify ](https://www.npmjs.com/package/js-beautify) | ✅ | |[MIT](https://github.com/beautify-web/js-beautify/blob/main/LICENSE)

**これを動作させるために必要なネットワークアクセスは？**

1. 動作には以下のホストが必要です  ```sh
  graph.microsoft.com
  login.microsoftonline.com

**参考** https://learn.microsoft.com/en-us/azure/active-directory/conditional-access/concept-conditional-access-conditions#device-platforms


> **重要** <br> *Microsoft では、サポートされていないデバイスプラットフォームに対して、条件付きアクセスポリシーを設定することを推奨しています。たとえば、Chrome OS やその他のサポートされていないクライアントから企業リソースへのアクセスをブロックする場合は、デバイスプラットフォーム条件として「任意のデバイス」を含め、サポートされているデバイスプラットフォームを除外し、[許可] コントロールを [アクセスをブロック] に設定したポリシーを構成してください。*

---

#### 参照の相違点


1. ロールの参照
> 条件としてロールが使用される場合、除外/包含の参照はロールのみによって決定されます。これにより、ポリシーがロールに対して正しく終了しても、結果ではそのロールに属するユーザーがポリシーから除外されたままになる可能性があります。結果では両方の条件が強調表示されます（マージされません）。これは、ユーザーまたはグループのコンテキストなしでロールの終了を個別に表示したいという設計上の決定によるものです。

 --- 

    Example:
    userID:0cd1b62d-5ff8-497b-9b56-9bb02bc0ab8c is included from All Apps policy

    There is admin policy, that covers role of Global administrator, but not the userId. 

    Both of following conditions would be shown in results:
    1. Role GA is excluded individually (1)
    2. UserId is not explicitly targeted by group or userId (0)

    All (cross-policy)	policies matched:1	users:Company Administrator
    All (cross-policy)	policies matched:0	users:joosua santasalo
    


---

2. グループの参照
> 逆に、グループが使用されている場合、ポリシーの終了はマージされ、ユーザーの除外はグループの包含によって終了したものとして表示されます。

    Example:
    userID:194383eb-6053-4d1e-bc72-f332be6ca2cb is included from All Apps policy

    There is policy which targets the user only by group

    Following conditions would be shown in results:
    1. User is excluded individually 
    2. User is targeted via group.

  
    All (cross-policy)	policies matched:1	users:Vihtori Santasalo (matched via group)


3. ゲストの参照
   
> このリリースでは、ユーザーはゲストとしてマップされません。この機能は後で導入される予定で、ゲスト userId の包含/除外を捕捉して ``GuestsOrExternalUsers`` プロパティに正しくマップできるようになります。
現在、ゲストユーザーは通常のユーザーと同じようにマップされます。
>

#### グループのネスト

  > パフォーマンス上の考慮により、グループのメンバーシップを解決するためのネスト深度は、グループが別のグループのグループである場合にのみ 1 回解決されます。そうしないと、サブグループがいずれかのルートグループを含む可能性があるため、メンバーシップが無期限に解決され、終わりのないループ状態になるリスクがあります。

    Membership:    
    Group1 -> all members resolved
    --> user is member of Group1
    --> Group2 is member of Group1 -> all members resolved to Group1
      --> Group3 is member of Group1 -> NOT RESOLVED

> もし挑戦するなら... コード内で直接ネストを増やすこともできます... [group.js](https://github.com/jsa2/caoptics/blob/main/ca/mainPlugins/userMappers/group.js)

![](https://assets.kitploit.com/production/public/readmes/47865/59681df621b6d006dbf9ae0a77045e5967665eb4000674c643fcc9a9e74ad856.png)  



## パラメータ

Param| Description 
-|-
``mapping`` | 既定では、ユーザーおよびグループベースの除外は、オブジェクトの正確な ID によって評価されます。たとえば、あるポリシーでオブジェクトが除外された場合、そのオブジェクトは別のポリシーで正確な ID によって見つかる必要があります。 <br> `` --mapping`` を使用すると、MS Graph を呼び出してオブジェクト間の関係を設定し、たとえば、あるポリシーで userId によってユーザーが除外されても、別のポリシーでは groupId によってそのユーザーが含まれていることを評価が検出できるようにします。 <br> 例: ``--mapping`` 
``clearMappingCache`` | 以前の実行で取得したユーザー/グループマッピングをクリアします <br> 例: ``--clearMappingCache`` 
``skipObjectId `` | 順列から ObjectId を削除します。結果から緊急用アカウント（break-glass account）を除外したい場合に便利です。 <br> 例: ``--skipObjectId=bcd27e9b-8974-42ec-a2a1-ba2498b45674,c7a4a639-00e7-47e0-aa9d-ea502bbbd382`` 
``skip `` | 順列カテゴリ全体を削除します。 <br> 例: ``--skip=users`` 
``includeReportOnly `` | reportOnly ポリシーを有効なポリシーと混在させることができます。実行前に、ルートにある policies.json ファイルを削除して既存のポリシーを削除するか、``clearPolicyCache`` オプションを使用してください。 <br> 例: ``--includeReportOnly`` 
``includeLegacyAuth `` | 既定では、レガシ認証条件のみを持つポリシーは評価されません。このフラグを使用すると、分析にレガシ認証を含めることができます。 <br> レガシ認証を含めると、サポートされているワークロード（AAD、SPO、EXO）だけでなく、すべてのアプリに対してレビューされることに注意してください。 <br> 例: ``--includeLegacyAuth`` 
``clearPolicyCache `` | ポリシーキャッシュを削除します <br> 例: ``--clearPolicyCache`` 
``clearTokenCache `` | トークンキャッシュを削除します <br> 例: ``--clearTokenCache`` 
``allTerminations`` | ポリシーで終了した結果も含めます <br> ``--allTerminations``
``debug`` | メモリ使用量と進捗の見積もりを表示します <br> 例: ``--debug``
``altLogin `` | 代替ログインエンドポイントの FQDN を定義できます <br> 例: ``--altLogin=login.microsoft.com.alt``
``altGraph `` | 代替 Graph エンドポイントの FQDN を定義できます <br> 例: ``--altGraph=graph.microsoft.com.alt`` 
``customPolicyFilter `` | ポリシーにカスタムフィルタリングを使用できます（ポリシーが期待されるスキーマに準拠していない場合にのみ推奨されます） <br> 例: ``--customPolicyFilter`` <br> フィルターは [``customPolicyFilter.js``](https://github.com/jsa2/caoptics/blob/main/ca/mainPlugins/customPolicyFilter.js) を選択して変更できます。 
``expand `` | 結果内で展開するグループを定義できます。既定では、グループは最初の 10 項目まで展開されます。展開する項目数は、``--expandCount=30`` オプションと組み合わせて増やすことができます。 <br> 例: ``--expand=9c06d103-f5b0-4404-bb25-aec4636912cd,47087cd3-64e9-470b-980a-5662f498e016`` <br> 注: このオプションを使用するには、マッピングキャッシュをクリアする必要があります ``--clearMappingCache`` 

### launch.json からパラメータを供給するには？（VSCode でのデバッグ）


現在の json スキーマをコピーして、``.vscode/launch.json`` フォルダー内に launch.json という名前のファイルを作成してください。```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
                "<node_internals>/**"
            ],
"program": "${workspaceFolder}/ca/main.js",
//"program": "${file}",
            "args":  [
                "--skipObjectId=259fcf40-ff7c-4625-9b78-cd11793f161f",
               "--mapping",
              "--clearMappingCache",
               "--clearPolicyCache",
               "--clearTokenCache",
               "--customPolicyFilter",
               "--allowPreviewPolicies=beta",
             //  "--altGraph=graph.microsoft.com",
              // "--allPlatforms",
             //   "--includeReportOnly",
                //"--inject",
            //"--clearPolicyCache",
              // "--skipCleaning",
             // "--allTerminations",
             // "--aggressive",
             "--debug",
            ],
            "runtimeArgs": [
                "--max-old-space-size=4096"
            ]
        }
    ]
  }

セッションが保存されていない場合、各実行でログインが開始されます。Azure CLI にセッションがあり、別のセッションを使用したい場合は、Azure CLI で ``Az Account Clear`` を実行してください 

1. 静的実行（[マッピング](#parameters) なし）
>``node ./ca/main.js `` 
2. 静的実行（[マッピング](#parameters) あり）
>``node ./ca/main.js --mapping`` 
3. ``skipObjectId=yourID`` を指定して Break glass グループを除外する
>``node ./ca/main.js --mapping  --skipObjectId=259fcf40-ff7c-4625-9b78-cd11793f161f`` 

また、このツールを試している場合は、``--clearPolicyCache --clearTokencache``  パラメータを含めることをお勧めします。これにより、既存のセッショントークンと policy.json（キャッシュ）が削除されます

>キャッシュからセッションを削除したくないが、ポリシーだけを削除したい場合は、プロジェクトフォルダから policies.json を削除してください

**期待される出力（サンプルデータに基づく）**

ポリシー | 順列 | 終了数 | ルックアップ 
 -|-|-|- 
All (cross-policy)| 33a51ecbcc58466a90b6bea66b239c74|  0| Locations:10a25087-9bf6-479b-a2a1-37e814310c90 -> Platforms:macOS -> clientAppTypes:mobileAppsAndDesktopClients -> users:All 
All (cross-policy)| 4194a5e64e054764bd8774d4992887b9|  0| Locations:10a25087-9bf6-479b-a2a1-37e814310c90 -> Platforms:macOS -> clientAppTypes:mobileAppsAndDesktopClients 
All (cross-policy)| 24f38821ea8e4331aeae7c078a727236|  1| Locations:10a25087-9bf6-479b-a2a1-37e814310c90 -> Platforms:macOS 


## レポートの表示
正常に実行されたすべての実行は、``crosstable.md``（Markdown テーブル）と CSV ``report.csv`` を出力します 
- ツールを実行するたびに、以前のレポートは消去されます

**.csv レポートの例**```
users                 Applications clientAppTypes              Platforms locations terminations  
-----                 ------------ --------------              --------- --------- ----------
GuestsOrExternalUsers All          browser                     macOS     finland   0
user-Joosua Santasalo All          browser                     macOS     finland   0
user-Joosua Santasalo All          mobileAppsAndDesktopClients macOS     finland   0
All                   All          browser                     macOS     finland   0

## トラブルシューティング

- セッションログインにAZ CLIを使用している場合は、``az account clear`` から始めてください
- ツールを実行する際は、``--clearPolicyCache --clearTokencache`` を追加してキャッシュ（トークン、ポリシー、場所）をクリアしてください
- 既存の policies.json と namedLocations.json をプロジェクトルートから手動で削除してください（``--clearPolicyCache --clearTokencache`` オプションを使用しない場合）
- グループの include が機能しない場合は、``--mapping`` が選択されていることを確認し、グループの入れ子が2レベルを超えていないことを確認してください

--- 

**Azure Cloud Shell でのテスト**

より大規模な環境でこのソリューションをテストする場合は、パラメータで ``--debug`` を有効にし、可能であれば Node.js のヒープサイズを `` --max-old-space-size=4096 `` に増やしてください。
  - テスト経験から、大規模な環境では順列の数が非常に多くなることがわかっています。デバッグモードで実行すると、問題が発生する箇所を特定するのに役立ちます。そのようなシナリオでは、Cloud Shell の使用は現実的でない可能性があります（順列アルゴリズムはメモリ使用量を大幅に削減しましたが、大規模な環境で Cloud Shell が機能することを確認できていません）。

> 現在の順列生成アルゴリズムは元のものより大幅に削減されているため、Cloud Shell でも動作するはずですが、たとえば競合状態やその他のメモリリークがまだどこかに潜んでおり、大規模な環境で顕在化して、現在のアルゴリズムの利点を損なう可能性があります。

``node --max-old-space-size=4096 ./ca/main.js --mapping  --skipObjectId=259fcf40-ff7c-4625-9b78-cd11793f161f --clearPolicyCache --debug`` 


---

- CAポリシーに空の参照がある可能性があり、その場合ルックアップは未終了の状態を示します

  >![](https://assets.kitploit.com/production/public/readmes/47865/7820044fc6c547017bca097b6a0306b341e689241ceea64b245f8a204c3269b4.png)  


# 貢献

リクエストの範囲に応じて、プルリクエストを開くか、イシューを提出してください。