improves docs

FeeiCN · Aug 28, 2017 · 46d5103 · 46d5103
1 parent 1801196
commit 46d5103
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 46 deletions.
diff --git a/cobra/__version__.py b/cobra/__version__.py
@@ -21,5 +21,5 @@
   {m} -t {td} -f json -o /tmp/report.json 
   {m} -t {tg} -f json -o [email protected] 
   {m} -t {tg} -f json -o http://push.to.com/api 
-  {m} -H 127.0.0.1 -P 80
+  sudo {m} -H 127.0.0.1 -P 80
 """.format(m='./cobra.py', td='tests/vulnerabilities', tg='https://github.com/wufeifei/vc.git')
diff --git a/docs/cli.md b/docs/cli.md
@@ -28,4 +28,50 @@ $ ./cobra.py --version
 
 # 查看帮助
 $ ./cobra.py --help
+```
+
+## Help（帮助）
+```bash
+➜  cobra git:(master) ✗ ./cobra.py --help
+usage: cobra [-h] [-t <target>] [-f <format>] [-o <output>] [-r <rule_id>]
+             [-d] [-sid SID] [-H <host>] [-P <port>]
+
+    ,---.     |
+    |    ,---.|---.,---.,---.
+    |    |   ||   ||    ,---|
+    `---``---``---``    `---^ v2.0.0
+
+GitHub: https://github.com/wufeifei/cobra
+
+Cobra is a static code analysis system that automates the detecting vulnerabilities and security issue.
+
+optional arguments:
+  -h, --help            show this help message and exit
+
+Scan:
+  -t <target>, --target <target>
+                        file, folder, compress, or repository address
+  -f <format>, --format <format>
+                        vulnerability output format (formats: html, json, csv,
+                        xml)
+  -o <output>, --output <output>
+                        vulnerability output STREAM, FILE, HTTP API URL, MAIL
+  -r <rule_id>, --rule <rule_id>
+                        specifies rules e.g: CVI-100001,cvi-190001
+  -d, --debug           open debug mode
+  -sid SID, --sid SID   scan id(API)
+
+RESTful:
+  -H <host>, --host <host>
+                        REST-JSON API Service Host
+  -P <port>, --port <port>
+                        REST-JSON API Service Port
+
+Usage:
+  ./cobra.py -t tests/vulnerabilities
+  ./cobra.py -t tests/vulnerabilities -r cvi-190001,cvi-190002
+  ./cobra.py -t tests/vulnerabilities -f json -o /tmp/report.json
+  ./cobra.py -t https://github.com/wufeifei/vc.git -f json -o [email protected]
+  ./cobra.py -t https://github.com/wufeifei/vc.git -f json -o http://push.to.com/api
+  sudo ./cobra.py -H 127.0.0.1 -P 80
 ```
diff --git a/docs/index.md b/docs/index.md
@@ -10,22 +10,22 @@
 > 对于一些需要判断参数是否可控的，Cobra通过预先梳理能造成危害的函数，并定位代码中所有出现该危害函数的地方，继而基于Lex(Lexical Analyzer Generator, 词法分析生成器)和Yacc(Yet Another Compiler-Compiler, 编译器代码生成器)将对应源代码解析为AST(Abstract Syntax Tree, 抽象语法树)，分析危害函数的入参是否可控来判断是否存在漏洞。
 
 ## Cobra和其它源代码审计系统有什么区别或优势？
-> Cobra目标是自动化发现源代码中大部分显著的安全问题，对于一些隐藏较深或企业特有的问题建议手工审计。
+> Cobra目标是自动化发现源代码中大部分显著的安全问题，对于一些隐藏较深或特有的问题建议手工审计。
 
 - 开源免费（基于开放的MIT License）
 - 支持开发语言多（支持十多种开发语言和文件类型）
 - 支持漏洞类型多（支持数十种漏洞类型）
 - 支持各种场景集成（提供API也可以命令行使用）
-- 持续维护更新（多家企业共同维护）
+- 多家企业使用，专业支持维护（由白帽子、开发工程师和安全工程师一起持续维护更新，并在多家企业内部使用）
 
 ## Cobra支持哪些开发语言？
-> 目前Cobra主要支持PHP、Java等主要开发语言及其它数十种文件类型，并持续更新规则和引擎以支持更多开发语言，具体见`languages`。
+> 目前Cobra主要支持PHP、Java等主要开发语言及其它数十种文件类型，并持续更新规则和引擎以支持更多开发语言，具体见支持的[开发语言和文件类型](https://wufeifei.github.io/cobra/languages)。
 
 ## Cobra能发现哪些漏洞？
-> 覆盖所有常见漏洞，具体见规则编写中的`labels`。
+> 覆盖大部分Web端常见漏洞和一些移动端（Android、iOS）通用漏洞，具体见支持的[漏洞类型](https://wufeifei.github.io/cobra/labels)。
 
 ## Cobra能应用在哪些场景？
-1. 【漏洞出现前】通过内置的扫描规则对公司项目进行日常扫描，并推进解决。
+1. 【漏洞出现前】通过内置的扫描规则对公司项目进行日常扫描，并推进解决发现的漏洞。
 2. 【漏洞出现后】当出现一种新漏洞，可以立刻编写一条Cobra扫描规则对公司全部项目进行扫描来判断受影响的项目。
 
 ## Cobra是什么类型应用？
@@ -34,6 +34,14 @@
 1. 部署成Web服务，提供自助扫描服务和API服务。
 2. 使用CLI模式，在命令行中进行扫描。
 
+## 如何参与Cobra开发或接入企业内部使用？
+> 如果你符合以下任何一项且对Cobra感兴趣，可加入我们的QQ群组（QQ群：578732936）。
+
+- 拥有Python开发经验
+- 有黑盒漏洞挖掘经验
+- 有白盒源码审计经验
+- 互联网相关企业想接入使用
+
 # Cobra文档
 - 安装
     - [Cobra安装](https://wufeifei.github.io/cobra/installation)

diff --git a/docs/rule_flow.md b/docs/rule_flow.md
@@ -10,43 +10,3 @@
 - 大写字母CVI（Cobra Vulnerability ID）开头，横杠（-）分割
 - 六位数字组成，前三位为Label ID，后三位为自增ID
 - 结尾以小写.xml结束
-
-## 规则编写规范
-
-|字段（英文）|字段（中文）|是否必填|类型|描述|例子|
-|---|---|---|---|---|---|
-|`name`|规则名称|是|`string`|描述规则名称|`<name value="Logger敏感信息" />`|
-|`language`|规则语言|是|`string`|设置规则针对的开发语言，参见`languages`|`<language value="php" />`|
-|`match`|匹配规则1|是|`string`|匹配规则1|`<match mode="regex-only-match"><![CDATA[regex content]]></match>`|
-|`match2`|匹配规则2|否|`string`|匹配规则2|`<match2 block="in-function-up"><![CDATA[regex content]]></match>`|
-|`repair`|修复规则|否|`string`|匹配到此规则，则不算做漏洞|`<repair block=""><![CDATA[regex content]]></match>`|
-|`level`|影响等级|是|`integer`|标记该规则扫到的漏洞危害等级，使用数字1-10。|`<level value="3" />`|
-|`solution`|修复方案|是|`string`|该规则扫描的漏洞对应的**安全风险**和**修复方案**|`<solution>详细的安全风险和修复方案</solution>`|
-|`test`|测试用例|是|`case`|该规则对应的测试用例|`<test><case assert="true"><![CDATA[测试存在漏洞的代码]]></case><case assert="false"><![CDATA[测试不存在漏洞的代码]]></case></test>`|
-|`status`|是否开启|是|`boolean`|是否开启该规则的扫描，使用`on`/`off`来标记|`<status value="1" />`|
-|`author`|规则作者|是|`attr`|规则作者的姓名和邮箱|`<author name="Feei" email="[email protected]" />`|
-
-## `<match>`/`<match2>`/`<repair>`编写规范
-
-#### `<match>` Mode（`<match>`的规则模式）
-> 用来描述规则类型，只能用在`<match>`中。
-
-|Mode|类型|默认模式|支持语言|描述|
-|---|---|---|---|---|
-|regex-only-match|正则仅匹配|是|*|默认是此模式，但需要显式的写在规则文件里。以正则的方式进行匹配，匹配到内容则算作漏洞|
-|regex-param-controllable|正则参数可控|否|PHP/Java|以正则模式进行匹配，匹配出的变量可外部控制则为漏洞|
-|function-param-controllable|函数参数可控|否|PHP|内容写函数名，将搜索所有该函数的调用，若参数外部可控则为漏洞。|
-|find-extension|寻找指定后缀文件|否|*|找到指定后缀文件则算作漏洞|
-
-#### `<match2>`/`<repair>` Block（`<match2>`/`<repair>`的匹配区块）
-> 用来描述需要匹配的代码区块位置，只能用在`<match2>`或`<repair>`中。
-
-|区块|描述|
-|---|---|
-| in-current-line | 由第一条规则触发的所在行 |
-| in-function | 由第一条规则触发的函数体内 |
-| in-function-up | 由第一条规则触发的所在行之上，所在函数体之内 |
-| in-function-down | 由第一条规则触发的所在行之下，所在函数体之内 |
-| in-file | 由第一条规则触发的文件内 |
-| in-file-up | 由第一条规则触发的所在行之上，所在文件之内 |
-| in-file-down | 由第一条规则触发的所在行之下，所在文件之内 |
diff --git a/docs/rule_template.md b/docs/rule_template.md
@@ -28,3 +28,44 @@
     <author name="Feei" email="[email protected]"/>
 </cobra>
 ```
+
+
+## 规则字段规范
+
+|字段（英文）|字段（中文）|是否必填|类型|描述|例子|
+|---|---|---|---|---|---|
+|`name`|规则名称|是|`string`|描述规则名称|`<name value="Logger敏感信息" />`|
+|`language`|规则语言|是|`string`|设置规则针对的开发语言，参见`languages`|`<language value="php" />`|
+|`match`|匹配规则1|是|`string`|匹配规则1|`<match mode="regex-only-match"><![CDATA[regex content]]></match>`|
+|`match2`|匹配规则2|否|`string`|匹配规则2|`<match2 block="in-function-up"><![CDATA[regex content]]></match>`|
+|`repair`|修复规则|否|`string`|匹配到此规则，则不算做漏洞|`<repair block=""><![CDATA[regex content]]></match>`|
+|`level`|影响等级|是|`integer`|标记该规则扫到的漏洞危害等级，使用数字1-10。|`<level value="3" />`|
+|`solution`|修复方案|是|`string`|该规则扫描的漏洞对应的**安全风险**和**修复方案**|`<solution>详细的安全风险和修复方案</solution>`|
+|`test`|测试用例|是|`case`|该规则对应的测试用例|`<test><case assert="true"><![CDATA[测试存在漏洞的代码]]></case><case assert="false"><![CDATA[测试不存在漏洞的代码]]></case></test>`|
+|`status`|是否开启|是|`boolean`|是否开启该规则的扫描，使用`on`/`off`来标记|`<status value="1" />`|
+|`author`|规则作者|是|`attr`|规则作者的姓名和邮箱|`<author name="Feei" email="[email protected]" />`|
+
+## 核心字段`<match>`/`<match2>`/`<repair>`编写规范
+
+#### `<match>` Mode（`<match>`的规则模式）
+> 用来描述规则类型，只能用在`<match>`中。
+
+|Mode|类型|默认模式|支持语言|描述|
+|---|---|---|---|---|
+|regex-only-match|正则仅匹配|是|*|默认是此模式，但需要显式的写在规则文件里。以正则的方式进行匹配，匹配到内容则算作漏洞|
+|regex-param-controllable|正则参数可控|否|PHP/Java|以正则模式进行匹配，匹配出的变量可外部控制则为漏洞|
+|function-param-controllable|函数参数可控|否|PHP|内容写函数名，将搜索所有该函数的调用，若参数外部可控则为漏洞。|
+|find-extension|寻找指定后缀文件|否|*|找到指定后缀文件则算作漏洞|
+
+#### `<match2>`/`<repair>` Block（`<match2>`/`<repair>`的匹配区块）
+> 用来描述需要匹配的代码区块位置，只能用在`<match2>`或`<repair>`中。
+
+|区块|描述|
+|---|---|
+| in-current-line | 由第一条规则触发的所在行 |
+| in-function | 由第一条规则触发的函数体内 |
+| in-function-up | 由第一条规则触发的所在行之上，所在函数体之内 |
+| in-function-down | 由第一条规则触发的所在行之下，所在函数体之内 |
+| in-file | 由第一条规则触发的文件内 |
+| in-file-up | 由第一条规则触发的所在行之上，所在文件之内 |
+| in-file-down | 由第一条规则触发的所在行之下，所在文件之内 |