设置 AppScan Presence 以直接扫描 GitHub 存储库

您可以使用 AppScan Presence 对 GitHub Enterprise 存储库运行静态分析。

AppScan Presence 包含可选的支持，可使用 GitHub 应用程序从 GitHub Enterprise 服务器对 GitHub 存储库运行静态分析。GitHub 服务器不一定可以公开访问；但是，AppScan 用户必须具有 GitHub 服务器的网络访问权限和 GitHub 存储库的访问权限。

启用了 GitHub 扫描的 AppScan Presence 实例可以使用服务器上定义的一个 GitHub 应用程序与一台 GitHub Enterprise 服务器关联。

要使用 AppScan Presence 连接并扫描 GitHub Enterprise 存储库：
  1. 创建 AppScan Presence 并将其安装到专用网络上可以访问 GitHub Enterprise 服务器的文件夹位置。
    注： 单个 Presence 连接到单个 GitHub 服务器，使组织中的所有用户可以扫描他们有权访问的服务器上的存储库。
  2. 在 GitHub Enterprise 服务器上创建 GitHub 应用程序。
  3. 在 AppScan Presence 中激活并配置 GitHub 特定的参数。
  4. 创建扫描。

创建 GitHub 应用程序

在开始前请查看 GitHub 应用程序的相关信息。

要创建 GitHub 应用程序来与 AppScan Presence 结合使用：

  1. 登录 GitHub。
  2. 选择设置 > 开发人员设置 > GitHub 应用程序，然后单击新建 GitHub 应用程序。
  3. 指定以下应用程序参数：
    参数 值
    GitHub 应用程序名称 应用程序的名称。
    描述 对应用程序的描述。例如，“连接到开发服务器的 ASoC 连接器。”
    主页 URL HCL AppScan on Cloud URL。例如，https://cloud.appscan.com。
    回调 URL 您的 AppScan Presence 嵌入式 Web 应用程序 URL 加 /signin-github。例如，https://my-presence-host-fqdn/signin-github。
    Webhook 取消选中活动
    存储库权限 内容和元数据设置为只读。
    帐户权限 电子邮件地址设置为只读。
    此 GitHub 应用程序可以安装在哪里? 任何帐户。
  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 应用程序时的 CallbackURL 相同。 https://my-presence-host-fqdn:443
    GithubAppId 您为此连接创建的 GitHub 应用程序的应用标识。 55
    GithubAppUrl GitHub 应用程序的安装 URL。 https://github01.example.com/github-apps/asoc
    ClientId GitHub 应用程序的客户机标识。 <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 Core Kestrel Web 服务器配置端点。
  5. 在拥有 GitHub 应用程序的帐户上安装该应用程序：
    1. 在浏览器中打开该应用程序的公共链接 (GithubAppUrl)。
    2. 安装应用程序。
    注： 不必为此次安装授予对专用存储库的访问权限，但应该在拥有该应用程序的帐户上安装该应用程序。
  6. 验证 Presence 系统和 GitHub 企业服务器上的时间设置是否同步。

设置了配置后，就可以启动（或重新启动）Presence 并开始扫描。日志写入控制台和日志文件夹下的日志文件中。

AppScan Presence GitHub 扫描流程

下图说明了使用 AppScan Presence 从 GitHub Enterprise 服务器扫描存储库的流程：

  1. 用户登录 ASoC。(1.2)
  2. 从 ASoC 中返回已配置启用的 AppScan Presence 和已连接服务器的列表。然后，用户选择要用于扫描的 GitHub 服务器。 ASoC 返回用于访问 AppScan Presence 服务器的 URL 和 GitHub 服务器的 URL
  3. 用户单击连接到 GitHub 时，ASoC 会打开新的浏览器选项卡，该选项卡指向 AppScan Presence (3) 以启动 oAuth 授权码流程。然后，用户被重定向到 GitHub Enterprise 服务器 (4)，登录并同意 AppScan Presence 访问 GitHub 帐户，然后使用授权码重定向回到 AppScan Presence
  4. AppScan Presence 从 GitHub Enterprise 服务器 (5) 获取用户访问令牌，并使用 window.postMessage 将令牌发回给用户 (3)，连同将令牌发送到 ASoC 的脚本一起发回。
  5. ASoC 使用 GitHub 访问令牌 (4) 获取用户和 AppScan Presence 使用的 GitHub 应用程序可访问的存储库列表。然后，用户可以选择要扫描的存储库。
  6. 在为所选的存储库创建扫描之前，ASoC 验证用户是否可以访问存储库。AppScan Presence API (3) 函数 RepoSignature 为存储库详细信息（存储库所有者和存储库名称）创建签名。一旦验证了访问权限，就会使用 AppScan Presence 独有的专用密钥对存储库详细信息进行签名。签名由 API 调用返回给 ASoC。
  7. ASoC 通过配置 AppScan Presence 标识 (Git Connect)、存储库详细信息和签名，使用 UsersAPI (2) 来创建扫描。UserAPI 使用与所提供的 AppScan Presence 实例关联的公用密钥来验证签名。如果验证成功，将为存储库创建扫描。
  8. AppScan Presence 服务会轮询 AppScan Presence WebAPI (6) 以查找任务，然后获取新任务以访存已扫描的存储库。Presence 使用关联的 GitHub 应用程序专用密钥连接到 GitHub Ent 服务器 (7)，以 zip 文件的形式访存存储库，并将文件流式传输到 Presence WebAPI (UploadRepo)
  9. 存储库 zip 文件存储在 ASoC 中，并且可供扫描。扫描完成后，用户可在 ASoC 中查看和分析结果。结果包含指向 GitHub Enterprise 服务器的链接，引用代码中用于筛选和补救的相关行。 ASoC 可以打开有相关代码的新选项卡。