ShiftLeft 学习笔记（一）_shiftleft()

一 基本声明

    本文是对shiftleft的一个基本翻译，帮助大家了解、学习这个东西。（严谨转载！欢迎讨论！）

二 基本介绍

What is ShiftLeft? 

ShiftLeft是为开发人员构建的下一代代码分析平台。

它的代码属性图(CPG)将应用程序的控制流、程序依赖项和抽象语法树描述为一个单一的数据结构，使您能够从根本上理解应用程序的每个版本的功能，并找到可能带来风险的任何场景。

快速在Linux/macOS和Windows学习基本的ShiftLeft。

For windows users

本教程向您展示如何使用ShiftLeft安装、设置、配置和运行您的第一个代码分析。

1 注册一个ShiftLeft帐户

系统将提示您创建一个组织。为您的组织提供一个名称，然后单击Create organization继续。记录组织ID和访问令牌

作为一个新的ShiftLeft用户，您将看到一个步骤列表，您需要完成这些步骤才能在仪表板中安装和设置ShiftLeft。如下图：

2 安装检查

2.1要安装Inspect，请下载sl.exe.

解压下载的文件，并运行新解压的可执行文件开始安装过程，确保授予安装程序请求的权限。这将sl.exe复制到C:\Program Files\ShiftLeft

2.2安装 Protect

如果您想在Inspect之外安装Protect, ShiftLeft提供了. net框架的安装程序。您必须使用具有管理员权限的帐户才能使用Windows安装程序。

步骤1：下载安装程序

获取.net框架安装程序

Invoke-WebRequest -URI https://cdn.shiftleft.io/download/installer-dotnet-framework-latest-windows-x64.zip -UseBasicParsing -OutFile sl-latest-windows-x64.zip

安装程序将所有依赖项捆绑到一个可下载的文件中。这使得安装程序可以在不需要访问Internet的情况下运行。

步骤2：解压缩下载的文件并运行安装程序

获得安装程序后，解压缩下载的文件。

运行新解压的可执行文件来开始安装过程。请务必授予安装程序请求的权限。

安装程序将Protect复制到C:\shiftleftDotNetAgent，在安装过程中，您将在命令提示窗口中看到状态更新。流程完成后，按Enter完成并关闭窗口。

命令行安装选项：（当从命令行运行安装程序时，请注意安装程序二进制文件有以下命令行选项可用来修改默认行为。）

所有目录都存储在Windows注册表中。

3 使用ShiftLeft CLI进行身份验证

ShiftLeft CLI命令sl auth用于使用ShiftLeft进行身份验证，并将您的应用程序与您的组织关联起来。

sl auth --org "YOUR_ORG_ID" --token "YOUR_ACCESS_TOKEN"

您可以从添加应用程序下的ShiftLeft仪表板获取YOUR_ORG_ID和YOUR_ACCESS_TOKEN的值。

这一步完成了两件事:使用ShiftLeft的API将您机器上运行的CLI与您的ShiftLeft帐户链接起来(调用该API需要包含令牌)。

可以证实或更新您的身份验证值在任何时间检查配置文件位于C:\Users\ {USER} \ .shiftleft \ json。

4 检查您的代码

此时，您就可以运行Inspect了。在本教程中，我们将测试HelloShiftLeft，这是一个使用Java构建的演示应用程序，用于演示ShiftLeft如何工作。必须安装Java 8才能使用HelloShiftLeft。

要获得ShiftLeft，您可以通过运行来克隆它的repo，在命令提示符中；

git clone https://github.com/ShiftLeftSecurity/HelloShiftLeft.git

克隆了repo之后，通过运行cd HelloShiftLeft导航到该文件夹。

通过运行mvn clean package来使用Maven构建应用程序(您也可以使用您选择的另一个构建工具)。如果成功，您可以期望将构建成功消息打印到命令提示符)。

运行ShiftLeft使用；

"C:\Program Files\ShiftLeft\sl.exe" analyze --app HelloShiftLeft --java target/hello-shiftleft-0.0.1.jar

您将看到以下输出：

根据打印到终端的指令，在5-10分钟后打开提供的URL。这将带您进入Dataflows页面;在右上角，单击“漏洞”查看代码中出现的问题。

三 Inspect（windows）

3.1 Getting start

本教程向您展示如何安装、设置和配置Inspect。（一部分内容同 二）

Inspect Your Code

此时，您就可以运行Inspect了。请参阅与您的应用程序相关的特定于语言的页面：

C#、Go、Java 、Scala

Analyzing Application

一旦您已经安装并使用ShiftLeft进行了身份验证，就可以使用Inspect来分析用以下语言编写的应用程序。

C#、Go、Java、JavaScript、Scala

识别秘密和热点

Inspect还可以用于识别应用程序中硬编码凭据和安全敏感函数的存在。

（这儿提供了不同编程语言的模块，我们以Java为例进行介绍）

Java

本文向您展示了如何分析用Java编写的应用程序。它假设您已经安装并使用ShiftLeft进行了身份验证。

1 要求：Inspect支持对用Java 7到Java 11编写的应用程序进行分析。

您的构建环境必须具有：

本地安装Java 8(根据您的应用程序开发需要，您可能需要同时运行多个Java版本)

至少有16Gb的可用内存

2 构建您的应用程序

Inspect的代码分析是在已编译的应用程序字节码上执行的(而不是在源代码上)。因此，在使用Inspect分析应用程序之前，必须先构建应用程序。

您可以考虑的一些构建工具包括Maven、Gradle、sbt等。

3 分析Java应用程序

要分析Java应用程序，请运行：

sl analyze --app <name> --java [<path>]

如果您使用的是类似JavaServer Pages (JSP)这样的模板框架，那么所分析的.jar / .war文件中就包含了这些模板。

4 内存

在运行代码分析时，我们建议使用堆大小，其中包括额外的20%，以确保服务器上有足够的物理内存来满足其他需求(例如，Java)。

为此，我们建议设置一个名为SHIFTLEFT_JAVA_OPTS的进程环境变量(例如，SHIFTLEFT_JAVA_OPTS=“-Xmx10g”)，该变量允许运行ShiftLeft来设置特定应用程序所需的堆内存。

5 CPG模式（代码属性图模式）

您可以选择使用代码属性图(CPG)模式来分析您的应用程序。使用CPG模式，ShiftLeft在本地构建CPG，然后将其(而不是应用程序的代码)上传到ShiftLeft云进行分析。

要使用CPG模式分析应用程序，请在sl分析命令中包含选项——CPG（sl analyze --app <name> --java --cpg <path>）

Working with Insight Parameters for Inspect

在使用Inspect分析代码时，您可以修改流程，以便扫描查找硬编码的凭据和安全敏感函数，并报告发现的内容以及已识别的任何其他漏洞。这是通过在您的sl分析命令中包含附加的Insights参数来实现的。

定义：当ShiftLeft扫描您的代码以查找硬编码的凭据时，它将查找硬编码的值(例如，客户端机密信息、用户名/密码组合)和敏感信息(例如，电话号码和地址)。

扫描安全敏感函数和硬编码凭据：若要查找所有硬编码凭据和安全敏感函数，请将--inspect-next添加到sl analyze命令行。

查找硬编码凭证：--insights="secrets"

寻找安全敏感的函数：--insights="hotspots"

查找安全敏感函数和硬编码凭据：--insights="secrets,hotspots"

例如，要在JavaScript应用程序中查找硬编码凭证和安全敏感函数，可以发出以下sl analyze命令：

sl analyze --js --no-cpg --insights="secrets,hotspots" -app yourAppName <path-to-your-app-directory>

查看你的结果

所有被ShiftLeft标识为存在于您的应用程序中的硬编码凭据和安全敏感函数都将出现在“漏洞仪表板”中。

CI/CD Integrations

ShiftLeft支持Inspect与您选择的持续集成和持续部署工具的集成，以提供自动化的代码分析。要将Inspect添加到您的构建和部署工作流中，请参阅您正在使用的工具的适当说明：Azure DevOps Bamboo Jenkins CircleCI Docker GoCD TeamCity Jira Travis

Vulnerabilities API

您使用漏洞API来查询关于代码漏洞的数据。漏洞是代码库中潜在的可利用路径。

该API按组织或应用程序版本返回一个漏洞列表，其中包含所有必要的信息，以便您对可开发的代码区域采取行动。

对API请求进行身份验证：任何公共API请求都需要通过将一个公共API令牌以以下形式：

Key: Authorization
Value: Bearer <your_token>

要获取令牌，请查看配置文件并复制在Public API Token部分提供的令牌。

一个API返回的例子

{
    "vulnerabilities": [
       {
           "applicationId": "project1549413585aa",
           "vulnerability": {
               "firstDetected": "041718202019.28",
               "vulnerabilityId": "database-write/e0ec210246d63ea44e28c01ed6113a66",
               "category": "a1-injection",
               "title": "Unsanitized database write in `DataLoader.run`",
               "description": "Attacker-controlled data is used in a database query without any sanitation or encoding. This could be intended behavior and thus has a low score. Injection flaws, such as SQL, NoSQL, OS, and LDAP injection, occur when untrusted data is sent to an interpreter as part of a command or query. By injecting hostile data, an attacker may trick the interpreter into executing unintended commands or accessing data without proper authorization which can result in data loss, corruption, or disclosure to unauthorized parties, loss of accountability, denial of access or even a complete host takeover.",
               "score": 1,
               "severity": "LOW_IMPACT",
               "securityEvents": "1",
               "blockedEvents": "1",
               "calls    ": "1",
               "locationURL": "/account/{accountId}/addInterest",
               "locationMethod": "addInterest",
               "status": "FIXED",
               "assignedTo": "example@shiftleft.io",
               "dataFlow": <dataFlowObject>
           }
       }
       ],
       "nextPageBookmark": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTczNTE3NDAsImlhdCI6MTU1NzM1MDg0MCwiaXNzIjoiU2hpZnRMZWZ0Iiwib3JkZXJfYnlfZGlyZWN0aW9uIjoxLCJpbmNsdWRlX2NhbGxzIjp0cnVlLCJDcmVhdGVkQXRCb29rbWFyayI6MTU1NzM0NDc3OH0.VzENvpKuho5iu4KT5R285PC033RPBAaq6xoqFSXg4uJQp1OTElcBYN6EOtunfE3ByahJqgigMXKFxSQ6GIti8AogQc0uQwJvtl6D3HPGvFvpIKdMDu3I77LpoaSMJXIaT3sb03Js78pEnUw0JyMhLBcwXjiC2lycEEWb5TE4zvgP5HE7uwPDTtObJeFQjmQq2fcQOqXFL_PbU2aISA9qgE9OdmX2bqX1my0YcvM0GnaCdNwAddWmvAngoz7GvSW8Uozxeqrs6JXGmHrSGoF4QWvW8klnBv8V92o5CazJuiW_O1nvFK4Yw1mA3ywbtmp6hERYF5EJ_uhx3RXv2YR2dw"

nextPageBookmark：包含要传递到相同端点以获得下一页结果(如果存在的话)的书签的字符串。

Pagination

ShiftLeft漏洞API端点始终分页。结果显示在最多包含50个结果的连续页面中。结果显示在三个类别根据严重程度。分页信息以nextPageBookmark的形式提供给每个响应访问下一页，每个页面的生命周期为15分钟。

{
      "vulnerabilities": [],
      "nextPageBookmark": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ...TGkubZyC69DRg",
     "totalResults": "155",
      "lowImpactResults": "104",
    "mediumImpactResults": "21",
    "highImpactResults": "30"
}

组织漏洞列表（组织的历史记录漏洞？）

使用以下请求按组织返回漏洞：

POST /api/v3/public/org/{organization id}/vulnerabilities/

结果返回带有以下标准的漏洞：

• Belonging to the latest analyzed version of any app

• Of any severity

• Of any category

• With any description

• With or without calls

• With or without blocked calls

• Arbitrarily sorted

• Only the first page (50 results)

过滤组织的漏洞：您可以在查询的主体中过滤返回

{
"query": {
        "orderByDirection": "VULNERABILITY_ORDER_DIRECTION_DESC",
        "applicationId": [
            "project1549413585aa"
        ],
        "statusFilter": [
            "VULNERABILITY_STATUS_UNKNOWN", "VULNERABILITY_STATUS_FIXED", "VULNERABILITY_STATUS_IGNORED", "VULNERABILITY_STATUS_ASSIGNED"
        ],
        "severityFilter": [],
        "typeFilter": "",
        "assignedToFilter": [],
        "returnRuntimeData": true,
        "hasRuntimeData": true
    }
  "pageBookmark": "eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTczNTE3NDAsImlhdCI6MTU1NzM1MDg0MCwiaXNzIjoiU2hpZnRMZWZ0Iiwib3JkZXJfYnlfZGlyZWN0aW9uIjoxLCJpbmNsdWRlX2NhbGxzIjp0cnVlLCJDcmVhdGVkQXRCb29rbWFyayI6MTU1NzM0NDc3OH0.VzENvpKuho5iu4KT5R285PC033RPBAaq6xoqFSXg4uJQp1OTElcBYN6EOtunfE3ByahJqgigMXKFxSQ6GIti8AogQc0uQwJvtl6D3HPGvFvpIKdMDu3I77LpoaSMJXIaT3sb03Js78pEnUw0JyMhLBcwXjiC2lycEEWb5TE4zvgP5HE7uwPDTtObJeFQjmQq2fcQOqXFL_PbU2aISA9qgE9OdmX2bqX1my0YcvM0GnaCdNwAddWmvAngoz7GvSW8Uozxeqrs6JXGmHrSGoF4QWvW8klnBv8V92o5CazJuiW_O1nvFK4Yw1mA3ywbtmp6hERYF5EJ_uhx3RXv2YR2dw"
}

pageBookmark：如果存在，查询将被忽略，并且如果存在此书签所指示的查询的下一页将被返回，这是可选的。

列出应用程序的漏洞：（检测的应用程序的漏洞）

您可以使用下面的请求来返回应用程序的漏洞：

POST /api/v3/public/org/{organization id}/app/{application id}/vulnerabilities/

结果返回带有以下标准的漏洞:

Belonging to the latest analyzed version this app.、Of any severity、Of any category、With any description、With or without calls、With or without blocked calls、Arbitrarily sorted、Only the first page (50 results)

要获取特定应用程序版本的结果，请使用：

POST /api/v3/public/org/{organization id}/app/{application id}/version/{version}/vulnerabilities

过滤应用程序的漏洞

{
"query": {
        "orderByDirection": "VULNERABILITY_ORDER_DIRECTION_DESC",
        "statusFilter": [
            "VULNERABILITY_STATUS_UNKNOWN", "VULNERABILITY_STATUS_FIXED", "VULNERABILITY_STATUS_IGNORED", "VULNERABILITY_STATUS_ASSIGNED"
        ],
        "severityFilter": [],
        "titleFilter": "",
        "assignedToFilter": [],
        "returnRuntimeData": true,
        "hasRuntimeData": true,
        "vulnerabilityId": "database-write/e0ec210246d63ea44e28c01ed6113a66"
        },
        "pageBookmark": ""
}

pageBookmark：如果存在，查询将被忽略，并且如果存在此书签所指示的查询的下一页将被返回，这是可选的。

How to Tag Inspect Results with the Git Branch Name

Inspect允许您提供分支名称，以便您能够区分一个分支与另一个分支的分析结果。

在Inspect生成的结果中包含分支信息

从版本控制系统获取分支名称。例如，Git允许您使用Git rev-parse——addrev-ref HEAD1来实现这一点。

将在上一步中获得的分支名称添加到使用——tag选项自动运行Inspect的脚本中（sl analyze --tag branch=<branchname>）

此时，ShiftLeft将在仪表板中显示来自代码分析的结果时包含分支名称。

Integrating Inspect into the GitHub Pull Request Workflow

本文概述了如何将ShiftLeft集成到GitHub工作流中，以便在创建新的Pull Request (PR)时自动检查分析代码，CircleCI构建应用程序。ShiftLeft分析过程是构建后的工作。

要求：我们假设您有CircleCI和GitHub帐户，并且使用Git作为源代码的版本控制系统；如果您更喜欢使用Jenkins而不是CircleCI，请参考下面的视频了解使用说明：https://docs.shiftleft.io/shiftleft/inspect/pr-workflow

步骤1：创建GitHub存储库

您将需要一个包含源代码的GitHub存储库，并且您的存储库应该包含.circleci/config。CircleCI在构建应用程序时查找的yml文件。

Inspect的分析是一个构建后的工作，您可以通过包含ShiftLeft Orb将此功能添加到您的CircleCI工作流中。如果这是您第一次使用第三方Orb，那么您需要选择使用第三方Orb。

步骤2：向CircleCI提供您的ShiftLeft凭据

请确保您已经创建了SHIFTLEFT_ORG_ID和SHIFTLEFT_ACCESS_TOKEN环境变量，以便CircleCI可以与ShiftLeft通信。您可以通过ShiftLeft仪表板获取这些变量的值(单击右上角的用户图标并单击帐户设置)。

步骤3：配置存储库

您将需要对存储库进行以下更改，您将在其中推动代码更改：

1 启用GitHub检查CircleCI设置

2 设置分支保护规则。为此，请导航到GitHub存储库。进入Settings > Branches ，在Branch protection rules区域，点击Add rule

3 在Branch name pattern下输入*，以确保该规则适用于所有分支

4 在“Branch name pattern”下，检查Require status checks to pass before merging，并在此存储库标题的最后一周中找到的状态检查中选择您希望需要的状态检查

5 滚动到页面底部，然后单击Create继续

步骤4：调用ShiftLeft获取结果

一旦Inspect分析了您的代码，您就可以为Inspect的分析结果调用ShiftLeft的Vulnerabilities API。ShiftLeft根据您的构建规则测试它的发现，构建规则用于测试漏洞类的存在，构建规则基于您创建的过滤器。实际上，您是在为ShiftLeft提供您认为可接受的实现参数。

您可以根据这些结果触发特定的操作。例如，您可以选择构建失败、触发电子邮件或Slack通知通知您的员工您的代码中存在漏洞，或其中的一些组合。

步骤5：回顾你的结果

如果需要，您可以手动检查检查分析的结果。在其结果输出中，Inspect将为您提供一个URL，您可以使用该URL访问ShiftLeft仪表板，该仪表板显示找到的漏洞。

对于每个识别的漏洞，您可以设置其状态，以指示需要做什么(如果有的话)工作。ShiftLeft提供以下状态值

我们还建议使用您选择的漏洞管理系统来跟踪已经完成的关于已识别的漏洞的工作，以及需要完成的工作。对于标记为忽略的项，您可以选择修改您的ShiftLeft策略来忽略这些类型的漏洞。

How to Work with Build Rules in Your Code Repository

在应用程序的存储库中，可以包含一个名为shiftleft的配置文件。包含构建规则的yml。ShiftLeft可以将其分析结果与构建规则进行比较，以确定构建是否应该失败。

有了这个文件，您就可以：

为每个应用程序/存储库指定不同的构建规则

将构建规则置于版本控制之下

编辑您的构建规则，而不需要开发工作流之外的单独工具

The shiftleft.yml File：默认情况下，配置文件在存储库中的位置应该是./shiftleft.yml。该文件的格式应该如下所示

build_rules:
  - id: build-rule-identifier
    severity:
      - SEVERITY_MEDIUM_IMPACT
      - SEVERITY_HIGH_IMPACT
    type:
      - SQL Injection
      - Sensitive Data Leak
    owasp_category:
      - a1-injection
    threshold: 10
  - id: another-build-rule
    severity:
      - SEVERITY_LOW_IMPACT
    threshold: 100

您可以在文件中包含多个构建规则。

以下是您可以在构建规则中包含的参数列表。所有构建规则参数都是可选的。