AppScan Presence を設定して GitHub リポジトリーを直接スキャンする

AppScan Presence を使用して、GitHub Enterprise リポジトリーで静的分析を実行できます。

AppScan Presence には、GitHub アプリを使用して GitHub Enterprise サーバーから GitHub リポジトリーで静的分析を実行するためのオプションのサポートが含まれています。GitHub サーバーにパブリックにアクセスできる必要はありません。ただし、AppScan ユーザーは GitHub サーバーへのネットワーク・アクセス権と GitHub 内のリポジトリーへのアクセス権を持っている必要があります。

GitHub スキャンが有効になっている AppScan Presence のインスタンスは、サーバー上で定義されている 1 つの GitHub アプリケーションを使用して、1 つの GitHub Enterprise サーバーに関連付けることができます。

AppScan Presence を使用して GitHub Enterprise リポジトリーに接続してスキャンするには、次の手順を実行します。
  1. GitHub Enterprise サーバーにアクセスできるプライベート・ネットワーク上のフォルダーの場所にAppScan Presence を作成 しインストールします。
    注: 組織内のすべてのユーザーは、単一 GitHub サーバーに接続された単一 Presence により、アクセス権のあるサーバー上のリポジトリーをスキャンできます。
  2. GitHub Enterprise サーバーに GitHub アプリを作成します。
  3. AppScan Presence で GitHub 固有のパラメーターをアクティブにして設定します。
  4. スキャンを作成します。

GitHub アプリケーションの作成

始める前に、GitHub アプリに関する情報を確認してください。

AppScan Presence で作業する GitHub アプリケーションを作成するには、次の手順を実行します。

  1. GitHub にログインします。
  2. 「設定」 > 「開発者設定」 > 「GitHub アプリ」の順に選択し、「新規 GitHub アプリ」をクリックします。
  3. 以下のアプリ・パラメーターを指定します。
    パラメーター 値
    GitHub App name アプリの名前
    説明 アプリの説明(例: 開発サーバーへの AppScan 360° コネクター)
    Homepage URL HCL AppScan 360° のURL例えば、https://<360domain> です。
    コールバック URL AppScan Presenceに埋め込まれた Web アプリケーションの URL に /signin-github を加えた URL。例えば、https://my-presence-host-fqdn/signin-github です。
    Webhook 「アクティブ」のチェックを外す
    Repository permissions 「コンテンツ」と「メタデータ」を「読み取り専用」に設定します。
    Account permissions 「電子メール・アドレス」を「読み取り専用」に設定します。
    Where can this GitHub App be installed? 任意のアカウント
  4. 「GitHub アプリの作成」をクリックします。
  5. GitHub アプリの設定を表示し、AppScan Presence を構成するために以下の値をメモします。
    • AppID
    • AppUrl
    • ClientId
    • ClientSecret

AppScan Presence の設定とアクティブ化

  1. GitHub アプリの秘密鍵を作成します。
    1. GitHub Enterprise の GitHub アプリ・ウィンドウで、「秘密鍵の生成」をクリックします。
    2. ダウンロードしたファイルの名前を GitHubAppKey.pem に変更し、Presence のインストール・フォルダーにコピーします。
  2. Presence のインストール・ディレクトリーで、git_connect_settings.json ファイルを探して開き、編集します。
  3. git_connect_settings.json の GitConnectOptions セクションで、次のようにパラメーターを編集します。
    パラメーター 説明 例
    GitServerName GitHub サーバーの名前 github01
    GitConnectUrl この AppScan Presence によって公開される Web アプリケーションの URL。これは GitHub アプリを作成したときのコールバック URL と同じ値です。 https://my-presence-host-fqdn:443
    GithubAppId この接続用に作成した GitHub アプリの AppID 55
    GithubAppUrl GitHub アプリのインストール URL https://github01.example.com/github-apps/asoc
    ClientId GitHub アプリのクライアント ID <oauth client id>
    ClientSecret GitHub アプリのクライアント・シークレット <oauth client secret>
    GitPlatformDomain GitHub Enterprise サーバーの URL https://github01.example.com
    Proxy GitHub サーバーへの接続にプロキシーが必要な場合は、この行をアンコメントしてプロキシーの詳細を入力 127.0.0.1:8888
    Active AppScan Presence で GitHub 接続機能を有効または無効にします。デフォルト値は false です。 true
  4. HTTPS を使用することを強くお勧めします。HTTP を使用することを選択すると、サイトは安全でないと見なされるため、安全でないコンテンツを許可するようにブラウザー設定を調整する必要があります。

    HTTPS を確実に使用するには、git_connect_settings.json の Kestrel セクションで、次のようにパラメーターを編集します。

    パラメーター 説明 例
    Http AppScan Presence に使用されるプロトコル Https
    Url AppScan Presence で使用されるポート http://*:8080
    注: AppScan Presence は Kestrel を使用して Web アプリケーションをホストします。Kestrel は組み込み Web サーバーであり、設定ファイルの「Kestrel」セクションで構成できます。このサーバー設定の構成について詳しくは、「ASP.Net コア Kestrel Web サーバーのエンドポイントの設定」を参照してください。
  5. GitHub アプリを所有するアカウントにインストールします。
    1. ブラウザーでアプリケーションのパブリック・リンク (GithubAppUrl) を開きます。
    2. アプリをインストールします。
    注: このインストールではプライベート・リポジトリーへのアクセス権を付与する必要はありませんが、アプリケーションはそれを所有するアカウントにインストールする必要があります。
  6. Presence システムと GitHub Enterprise サーバーの時刻設定が同期していることを確認します。

設定が完了すると、Presence を開始 (または再起動) してスキャンを開始できます。ログはコンソールと logs フォルダー下にあるログ・ファイルに書き込まれます。

AppScan Presence GitHub スキャン・フロー

次の図は、AppScan Presence を使用して GitHub Enterprise サーバーからリポジトリーをスキャンする手順を示しています。

  1. ユーザーが AppScan 360° にログインします。(1、2)
  2. AppScan 360° から、接続されているサーバーで設定されている有効な AppScan Presence のリストが返されます。次に、ユーザーがスキャンに使用する GitHub サーバーを選択します。 AppScan 360° AppScan Presence サーバーにアクセスするための URL と GitHub サーバーへの URL を返します。
  3. ユーザーが「GitHub に接続」をクリックすると、AppScan 360° に新しいブラウザー・タブが開かれ、oAuth 認可コード・フローが開始される AppScan Presence がポイントされます (3)。その後、ユーザーは GitHub Enterprise Server (4) にリダイレクトされ、ログインして AppScan Presence が GitHub アカウントにアクセスすることに同意すると、認証コードとともに AppScan Presence にリダイレクトされます。
  4. AppScan Presence は GitHub Enterprise Server (5) からユーザー・アクセス・トークンを取得し、window.postMessage を使用してトークンを AppScan 360° に送信するスクリプトとともにユーザー (3) に返します。
  5. AppScan 360° は GitHub アクセス・トークンを使用して (4)、ユーザーがアクセスできるリポジトリーと、AppScan Presence が使用する GitHub アプリのリストを取得します。ユーザーはスキャンするリポジトリーを選択できます。
  6. 選択したリポジトリーのスキャンを作成する前に、AppScan 360° はリポジトリーがユーザーによってアクセス可能であることを確認します。AppScan Presence API (3) 関数 RepoSignature は、リポジトリーの詳細 (リポジトリーの所有者とリポジトリーの名前) の署名を作成します。アクセスが検証されると、リポジトリーの詳細に AppScan Presence 固有の秘密鍵で署名されます。署名は、API 呼び出しによって AppScan 360° に返されます。
  7. AppScan 360° AppScan Presence ID (Git Connect)、リポジトリーの詳細、署名をプロビジョニングし、UsersAPI を使用してスキャンを作成します (2)。UserAPI は、指定された AppScan Presence インスタンスに関連付けられた公開鍵を使用して署名を検証します。検証が成功すると、リポジトリーのスキャンが作成されます。
  8. AppScan Presence サービスは AppScan Presence WebAPI にタスクをポーリングし (6)、スキャンされたリポジトリーを取得するための新しいタスクを取得します。Presence は、関連付けられた GitHub アプリケーションの秘密鍵を使用して GitHub Enterprise サーバー に接続し (7)、リポジトリーを ZIP ファイルとして取得して Presence WebAPI (UploadRepo) にストリームします。
  9. リポジトリーの ZIP ファイルは AppScan 360° に保存され、スキャンできます。スキャンが完了すると、結果が AppScan 360° に表示され、分析されます。結果には、GitHub Enterprise Server へのリンクが含まれており、コード内の関連する行を参照してトリアージと修復を行います。 AppScan 360° 関連するコードを含む新しいタブを開くことができます。