Skip to content

xAST评价体系开发规范

Jump to bottom
AntJiuFo edited this page Dec 17, 2024 · 17 revisions

xAST评价体系的开发包括2部分，一是评价项，二是评价项对应的Benchmark代码。

评价项的开发

评价项通常按[应用安全产品类型+语言+引擎/规则]进行命名。评价项一般是树状结构，按不同评价维度进行分类，需要先确定评价项所处的位置。

Benchmark代码

在参与Benchmark case的新增/修改时，要注意将case放在相应的目录结构并采用合适的命名、在case的代码中进行注释添加，以及添加case后进行相应wiki内容的更新。

要求一个评价case单独占一个文件，目录结构的设置以及case文件的命名方式按照如下标准进行。
若一个评价case无法单独占一个文件，可新建一个单独的规范附在wiki中说明，为共建时的case命名提供指引。

目录结构

目录的第一级为产品+语言，如iast-java、sast-node等。
目录的第二级为评价目标，即评价产品的引擎能力还是产品的检测规则丰富度，用engine/rule表示。
文件的每一级目录代表一种评价类型，相同类型的case放在统一类型目录下。请尽量使各个case文件的相对深度尽量一致，且不要太深。一些较细的类型不需要额外拆解，放在文件名中即可。各级文件目录均采用驼峰命名法。注意，每一级文件夹的命名均请采用驼峰命名法。

举例说明，以SAST为例：
Lambda表达式这个场景的case在脑图中的结构如下：
image 可以对应文件结构：
cases/completeness/base/chain/astTaint/Expression_Lamda_001_T.java
像这里，把Expression、If都展开做目录就没必要了。由于太细，可以直接放在文件名中。

一些其他的case结构示例：
cases/completeness/base/chain/astTaint/Expression_If_001_T.java
cases/completeness/base/chain/sink/ClassSelfDefinition_001_T.java
cases/completeness/base/object/protogenesis/Set_Map_001_T.java
cases/completeness/base/object/protogenesis/Array_String_001_T.java
cases/completeness/asynchronous/storage/Session_001_T.java

文件名称

目录的第一级为产品+语言，如iast-java、sast-node等。
目录的第二级为评价目标，即评价产品的引擎能力还是产品的检测规则丰富度，用engine/rule表示。
一个文件只放一个case，文件命名实际就是case的类命名，更加便于管理和展示。另外，一个文件一个case，在新增、删除、调整case的时候可以完成互不影响。
命名结构如下所示：
【类型】_【递增标识符】_【预期是否被检出，即是真case还是假case，用T/F标识】
如：
Expression_If_001_T.java
ClassSelfDefinition_001_T.java
Set_Map_001_T.java
ObjectProperty_002_F.java

注意，可以将不宜拆解在目录结构中的较细的子类型放在【类型】中，并以'_'进行分割。如上面举的例子Expression_If_001_T.java，Exprssion是一种AST的节点，但是单独拆为一个目录并不合适。因此放在命名中，以Expression_If命名，再加上递增标识符001，再标明是否预期被检出。
若想增加相同类型的case，找到相关的目录，进行按标识符进行递增创建新的文件即可。注意，由于文件名往往会作为类的名称，请将每一个_区分开的单词首字母大写。

case代码规范

在每一个case文件中，需要在类的定义前增加注释。内容包括两部分：
对case本身的描述

  • 简要介绍 (Introduction) - 简要介绍该case对应的场景。
  • 难度等级 (Level) - 该case对应的难度等级，当前难易等级评定标准还未确定，可以暂时标记为X。
  • 日期 (Date) - 该case增加/改动时间。

对case和评价项对应关系的描述

  • 使用单行注释
  • real vulnerability，当前case是真漏洞，还是假漏洞，要和文件名中的标识一致
  • assession project，写出完整评价项链路，注意，如果当前出现在相同compose中的所有case的assession project需要保持一致，代表共同评价了这一个评价项
  • compose，评价项计算逻辑，当逻辑计算为true时，代表评价项可达成， 可以使用 与&& 或|| 非! 合并()四种逻辑
  • bind_url，当前这个case对应的完整url
  • assession information start/end，对应关系注释标识，必须填写，以便工具读出当前case和评价项对应关系

case的函数名

  • 由于一个case对应一个文件，由文件名以及相应的类名确定，因此新增case的函数名可统一为testcase()。

举例如下，以下为Expression_If_Discriminant_001.js的内容。
这里compose中有三个case，那么这三个case的assession project必须一致，即这三个case共同评价了三方包方法跟踪这个评价项

const { Controller } = require('egg');
const { execSync } = require('child_process');

/**
 * Introduction AST节点中的If表达式，且污点传递过程在if表达式的判定条件中
 * Level X
 * Date 2024-01-01
 */
// evaluation information start
// real vulnerability = true
// evaluation item  = 完整度->基础跟踪能力->污点链路完整度->特殊链路跟踪能力->三方包方法跟踪
// compose = Expression_If_Discriminant_001_T.js && (Expression_If_Discriminant_002_T.js && !Expression_If_Discriminant_003_F.js)
// bind_url = /a/b/c/
// evaluation information end

@RequestMapping("completeness/base/chain/astTaint")
class Expression_If_Discriminant_001_T extends Controller {
  @GetMapping("Expression_If_Discriminant_001_T")
  async testcase(){
    var a= this.ctx.query.a;
    if( typeof execSync(a) =='string'){
      this.ctx.body = `Output: \n${res}`;
    }
    else{
      this.ctx.body = `Output: not string`;
    }
  }

}

module.exports = Expression_If_Discriminant_001;

config.json文件配置

若想使用XAST自带的评价报告生成tool，需要按规范填写config.json，在每个评价项文件夹内都会有一个config.json文件，表示当前文件夹下的评价项和case的对应关系，以及该评价项的成熟度分级（这也是我们的一个重点工作，针对语言特性进行了成熟度分级，可以客观定位SAST工具所处等级，预计于2024年底发布）。
config.json格式示例如下：

{
  "return_value_passing": [ // 此处为该评价项所处大类，通常为文件夹名称
    {
      "evaluation item": "完整度->链路跟踪完整度->函数调用->返回值传递->普通", // 此处为该评价项
      "compose": "return_value_passing_001_T.java && !return_value_passing_002_F.java", // 此处为该评价项达成需要满足的case检出情况
      "level": "2" // 此处为该评价项的成熟度分级
    },
    { // 如果有多个，罗列在下面即可
      "evaluation item": "完整度->链路跟踪完整度->函数调用->返回值传递->xxxxx", 
      "compose": "xxxxxx",
      "level": "2"
    }
  ]
}
Clone this wiki locally