Report · Vuls

report:
  report
    [-lang=en|ja]
    [-config=/path/to/config.toml]
    [-results-dir=/path/to/results]
    [-log-dir=/path/to/log]
    [-refresh-cve]
    [-cvss-over=7]
    [-diff]
    [-diff-minus]
    [-diff-plus]
    [-ignore-unscored-cves]
    [-ignore-unfixed]
    [-ignore-github-dismissed]
    [-to-email]
    [-to-http]
    [-to-slack]
    [-to-chatwork]
    [-to-telegram]
    [-to-localfile]
    [-to-s3]
    [-to-azure-blob]
    [-to-saas]
    [-format-json]
    [-format-one-email]
    [-format-one-line-text]
    [-format-list]
    [-format-full-text]
    [-gzip]
    [-http-proxy=http://192.168.0.1:8080]
    [-debug]
    [-debug-sql]
    [-quiet]
    [-no-progress]
    [-pipe]
    [-http="http://vuls-report-server"]
    [-trivy-cachedb-dir=/path/to/dir]

    [RFC3339 datetime format under results dir]
  -config string
      /path/to/toml (default "/Users/kanbe/go/src/github.com/future-architect/vuls/config.toml")
  -cvss-over float
      -cvss-over=6.5 means reporting CVSS Score 6.5 and over (default: 0 (means report all))
  -debug
      debug mode
  -debug-sql
      SQL debug mode
  -diff
      Plus & Minus Difference between previous result and current result
  -diff-minus
      Minus Difference between previous result and current result
  -diff-plus
      Plus Difference between previous result and current result
  -format-full-text
      Detail report in plain text
  -format-json
      JSON format
  -format-list
      Display as list format
  -format-one-email
      Send all the host report via only one EMail (Specify with -to-email)
  -format-one-line-text
      One line summary in plain text
  -gzip
      gzip compression
  -http-proxy string
      http://proxy-url:port (default: empty)
  -ignore-github-dismissed
      Don't report the dismissed CVEs on GitHub Security Alerts
  -ignore-unfixed
      Don't report the unfixed CVEs
  -ignore-unscored-cves
      Don't report the unscored CVEs
  -lang string
      [en|ja] (default "en")
  -log-dir string
      /path/to/log (default "/var/log/vuls")
  -pipe
      Use args passed via PIPE
  -quiet
      Quiet mode. No output on stdout
  -refresh-cve
      Refresh CVE information in JSON file under results dir
  -results-dir string
      /path/to/results (default "/Users/kanbe/go/src/github.com/future-architect/vuls/results")
  -to-azure-blob
      Write report to Azure Storage blob (container/yyyyMMdd_HHmm/servername.json/xml/txt)
  -to-chatwork
      Send report via chatwork
  -to-email
      Send report via Email
  -to-http
      Send report via HTTP POST
  -to-localfile
      Write report to localfile
  -to-s3
      Write report to S3 (bucket/yyyyMMdd_HHmm/servername.json/xml/txt)
  -to-saas
      Upload report to Future Vuls(https://vuls.biz/) before report
  -to-slack
      Send report via Slack
  -to-syslog
      Send report via Syslog
  -to-telegram
      Send report via Telegram
  -trivy-cachedb-dir string
      /path/to/dir (default "/Users/hoge/Library/Caches/trivy")

3つのフォーマットオプションの例

Vulsには3つのフォーマットオプションがあります。

format-list(default)
format-one-line-text
format-full-text

format-list

report-list

$ vuls report

c74 (centos7.4.1708)
====================
Total: 294 (High:65 Medium:198 Low:24 ?:7), 93/294 Fixed, 708 installed, 285 updatable

+------------------+------+----------+---------+---------------------------------------------------+
|      CVE-ID      | CVSS |  ATTACK  |  FIXED  |                        NVD                        |
+------------------+------+----------+---------+---------------------------------------------------+
| CVE-2017-11176   | 10.0 |  Network |   Fixed | https://nvd.nist.gov/vuln/detail/CVE-2017-11176   |
| CVE-2017-12762   | 10.0 |  Network | Unfixed | https://nvd.nist.gov/vuln/detail/CVE-2017-12762   |
| CVE-2017-18017   | 10.0 |  Network |   Fixed | https://nvd.nist.gov/vuln/detail/CVE-2017-18017   |
| CVE-2017-1000158 |  9.8 |  Network | Unfixed | https://nvd.nist.gov/vuln/detail/CVE-2017-1000158 |
| CVE-2017-10684   |  9.8 |  Network | Unfixed | https://nvd.nist.gov/vuln/detail/CVE-2017-10684   |
| CVE-2017-10685   |  9.8 |  Network | Unfixed | https://nvd.nist.gov/vuln/detail/CVE-2017-10685   |
... snip ...

format-one-line-text

$ vuls report -format-one-line-text

One Line Summary
================
c74     Total: 294 (High:65 Medium:198 Low:24 ?:7)      93/294 Fixed    708 installed, 285 updatable
deb8    Total: 490 (High:62 Medium:158 Low:22 ?:248)    11/490 Fixed    512 installed

format-full-text

report-list

$ vuls report -format-full-text

c74 (centos7.4.1708)
====================
Total: 23 (High:22 Medium:1 Low:0), 9/23 Fixed, 708 installed, 285 updatable

+---------------+----------------------------------------------------------------------------------+
| CVE-2017-9233 |                                                                                  |
+---------------+----------------------------------------------------------------------------------+
| Max Score     | 7.5 HIGH (nvd)                                                                   |
| nvd           | 7.5/CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H HIGH                            |
| redhat_api    | 6.5/CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:U/C:N/I:N/A:H MODERATE                        |
| nvd           | 5.0/AV:N/AC:L/Au:N/C:N/I:N/A:P MEDIUM                                            |
| Summary       | XML External Entity vulnerability in libexpat 2.2.0 and earlier (Expat XML       |
|               | Parser Library) allows attackers to put the parser in an infinite loop using a   |
|               | malformed external entity definition from an external DTD.                       |
| Mitigation    |  Do not parse untrusted arbitrary XML data using the expat                       |
|               | package.                                                                         |
| CWE           | CWE-835: Loop with Unreachable Exit Condition ('Infinite Loop') (redhat_api)     |
| CWE           | [OWASP Top4] CWE-611: Improper Restriction of XML External Entity Reference      |
|               | ('XXE') (nvd)                                                                    |
| Affected PKG  | expat-2.1.0-10.el7_3 -> Will not fix                                             |
| Confidence    | 100 / RedHatAPIMatch                                                             |
| Source        | https://nvd.nist.gov/vuln/detail/CVE-2017-9233                                   |
| CVSSv2 Calc   | https://nvd.nist.gov/vuln-metrics/cvss/v2-calculator?name=CVE-2017-9233          |
| CVSSv3 Calc   | https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?name=CVE-2017-9233          |
| RHEL-CVE      | https://access.redhat.com/security/cve/CVE-2017-9233                             |
| CWE           | https://cwe.mitre.org/data/definitions/CWE-835.html                              |
| CWE           | https://cwe.mitre.org/data/definitions/CWE-611.html                              |
| OWASP Top10   | https://github.com/OWASP/Top10/blob/master/2017/en/0xa4-xxe.md                   |
+---------------+----------------------------------------------------------------------------------+

... snip ...

c74 (centos7.4.1708)
====================
Total: 23 (High:22 Medium:1 Low:0), 9/23 Fixed, 708 installed, 285 updatable

c74 means that it is a scan report of servers.c74 defined in config.toml.
(centos7.4.1708) は、OSがCentOS7.4であることを意味します。
Total: 23 (High:22 Medium:1 Low:0) は、全部で23の脆弱性があること、そして表示されている通りのCVSS深刻性があることを意味します。
9/23 Fixedは、全部で23の脆弱性があること、そしてそのうち9個が修正済みであること、残りの14個が未修正であることを意味します。
285 updatable packages means that there are 285 update-able packages on the target server.

+---------------+----------------------------------------------------------------------------------+
| CVE-2017-9233 |                                                                                  |
+---------------+----------------------------------------------------------------------------------+
| Max Score     | 7.5 HIGH (nvd)                                                                   |
| nvd           | 7.5/CVSS:3.0/AV:N/AC:L/PR:N/UI:N/S:U/C:N/I:N/A:H HIGH                            |
| redhat_api    | 6.5/CVSS:3.0/AV:N/AC:L/PR:N/UI:R/S:U/C:N/I:N/A:H MODERATE                        |
| nvd           | 5.0/AV:N/AC:L/Au:N/C:N/I:N/A:P MEDIUM                                            |
| Summary       | XML External Entity vulnerability in libexpat 2.2.0 and earlier (Expat XML       |
|               | Parser Library) allows attackers to put the parser in an infinite loop using a   |
|               | malformed external entity definition from an external DTD.                       |
| Mitigation    |  Do not parse untrusted arbitrary XML data using the expat                       |
|               | package.                                                                         |
| CWE           | CWE-835: Loop with Unreachable Exit Condition ('Infinite Loop') (redhat_api)     |
| CWE           | [OWASP Top4] CWE-611: Improper Restriction of XML External Entity Reference      |
|               | ('XXE') (nvd)                                                                    |
| Affected PKG  | expat-2.1.0-10.el7_3 -> Will not fix                                             |
| Confidence    | 100 / RedHatAPIMatch                                                             |
| Source        | https://nvd.nist.gov/vuln/detail/CVE-2017-9233                                   |
| CVSSv2 Calc   | https://nvd.nist.gov/vuln-metrics/cvss/v2-calculator?name=CVE-2017-9233          |
| CVSSv3 Calc   | https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator?name=CVE-2017-9233          |
| RHEL-CVE      | https://access.redhat.com/security/cve/CVE-2017-9233                             |
| CWE           | https://cwe.mitre.org/data/definitions/CWE-835.html                              |
| CWE           | https://cwe.mitre.org/data/definitions/CWE-611.html                              |
| OWASP Top10   | https://github.com/OWASP/Top10/blob/master/2017/en/0xa4-xxe.md                   |
+---------------+----------------------------------------------------------------------------------+

Max Score は、Max CVSS Scoreを意味します。
nvd はNVDの CVSS Vector です。
redhat はRed Hat OVALの CVSS Vector です。
jvn はJVNのCVSS Vector です。
CWE はそのCVEのCWE - Common Weakness Enumeration を意味します。
[OWASP Top10] はそのCWEが OWASP TOP 10 にあることを意味します。
Affected PKG はその脆弱性を含むパッケージのバージョンの情報を示します。
Confidence はその検知の信頼度を意味します。
- 100 は信頼度が高い。
- YumUpdateSecurityMatch はその脆弱性を検知した手法です。

Confidence のリスト

検知方法	信頼度	OS	説明
OvalMatch	100	CentOS, RHEL, Oracle, Ubuntu, Debian, SUSE	OVALによる検知
YumUpdateSecurityMatch	100	RHEL, Amazon, Oracle	yum-plugin-securityによる検知
ChangelogExactMatch	95	CentOS, Ubuntu, Debian, Raspbian	チェンジログに記載されているバージョンとそのパッケージのバージョンの完全一致
ChangelogLenientMatch	50	Ubuntu, Debian, Raspbian	チェンジログに記載されているバージョンとそのパッケージのバージョンの大まかな一致
PkgAuditMatch	100	FreeBSD	pkg auditによる検知
CpeNameMatch	100	All	config.tomlに記載されたCPEを用いたNVDの検索

Example: Generate all client scan reports

# Show scan history
$ vuls history

# Generate reports for all scan history
$ for REPORT_DATE in $(vuls history | awk '{ print $1 }') ; do echo "$REPORT_DATE" | vuls report -format-one-line-text -pipe ; done

# Generate reports for a specific date
vuls history | grep "DATE" | vuls report -format-one-line-text -pipe

Example: Difference between previous result and current result

The -diff-plus option detects new or updated vulnerabilities compared to the previous json.The one with _diff.json is output. The -diff-minus option detects vulnerabilities that have already been patched compared to the previous json.The one with _diff.json is output. -diff option turns on both options -diff-plus and -diff-minus

# After vuls scan, get minus difference.
$ vuls report -diff-minus -to-localfile -format-json

Example: Specify the path of go-cve-dictionary, goval-dictionary and gost

config.toml

[cveDict]
type = "sqlite3"
SQLite3Path = "/path/to/cve.sqlite3"

[ovalDict]
type = "sqlite3"
SQLite3Path = "/path/to/oval.sqlite3"

[gost]
type = "sqlite3"
SQLite3Path = "/path/to/gost.sqlite3"

[exploit]
type = "sqlite3"
SQLite3Path = "/path/to/go-exploitdb.sqlite3"

[metasploit]
type = "sqlite3"
SQLite3Path = "/path/to/go-msfdb.sqlite3"

Example: Send scan results to another endpoint

Define HTTP section in config.toml

$ vuls report \
      -to-http \
      -format-json

Sample PHP code on the endpoint side:

<?php
$tmp_file = __DIR__ . '/vuls-'. uniqid() . '.json';
file_put_contents($tmp_file, file_get_contents("php://input"));
if (file_exists($tmp_file)) {
    $raw_json_data = file_get_contents($tmp_file);
    $json_data = json_decode($raw_json_data);
    $scanned_hostname = $json_data->{'serverName'};
    $new_file = __DIR__ . '/' . strtolower($scanned_hostname) . '.json';
    rename($tmp_file, $new_file);
}
?>

Source: vuls.php

The following code will simply create a JSON file named with the hostname extracted that way hostname.json. It will be created in the same location of the vuls.php file.

Example: Send scan results to email

Define EMail section in config.toml

$ vuls report \
      -to-email \
      -cvss-over=7

With this sample command, it will ..

Send scan results to Email
CVSSスコアが7以上のCVEのみをレポートします。

Example: Send scan results to ChatWork

Define ChatWork section in config.toml

$ vuls report \
      -to-chatwork \
      -cvss-over=7

With this sample command, it will ..

Send scan results to ChatWork
CVSSスコアが7以上のCVEのみをレポートします。

Example: Send scan results to Slack

Define Slack section in config.toml

$ vuls report \
      -to-slack \
      -cvss-over=7

With this sample command, it will ..

Send scan results to slack
CVSSスコアが7以上のCVEのみをレポートします。

Example: Send scan results to Telegram

Define Telegram section in config.toml

$ vuls report \
      -to-telegram \
      -cvss-over=7

With this sample command, it will ..

Send scan results to Telegram
CVSSスコアが7以上のCVEのみをレポートします。

Example: Put results in S3 bucket

To put results in S3 bucket, configure following settings in AWS before reporting.

Create S3 bucket. See Creating a Bucket
Configure access to S3 resources. You can do this in several ways:
- Configure the environment variables. See Configuring the AWS Command Line Interface
- Configure the security credentials. See Configuring the AWS Command Line Interface
- Create an IAM role for the service and attach it to the service (EC2, AWS Lambda). Creating a Role to Delegate Permissions to an AWS Service
To configure environment variables, security credentials, create an access key. See Managing Access Keys for IAM Users

Example of IAM policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListAllMyBuckets"
            ],
            "Resource": "arn:aws:s3:::*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "s3:PutObject"
            ],
            "Resource": "arn:aws:s3:::vuls/*"
        }
    ]
}

config.toml

[aws]
profile = "default"
region = "ap-northeast-1"
s3Bucket = "vuls"
s3ServerSideEncryption = "AES256"

reporting

$ vuls report \
      -to-s3 \
      -format-json

With this sample command, it will ..

Put scan result(JSON) in S3 bucket

with AES256
bucket name is "vuls"
ap-northeast-1
profile is "default"
The Server-side encryption algorithm (e.g., AES256, aws:kms).

Example: Put results in Azure Blob storage

To put results in Azure Blob Storage, configure following settings in Azure before reporting.

Create a Azure Blob container

config.toml

[azure]
accountName = "default"
accountKey = "xxxxxxxxxxxxxx"
containerName "vuls"

$ vuls report -to-azure-blob
...

With this sample command, it will ..

Put scan result(JSON) in Azure Blob Storage.

container name is "vuls"
storage account is "test"
accesskey is "access-key-string"

account and access key can be defined in environment variables.

$ export AZURE_STORAGE_ACCOUNT=test
$ export AZURE_STORAGE_ACCESS_KEY=access-key-string
$ vuls report -to-azure-blob

Example: IgnoreCves

Define ignoreCves in config if you don't want to report(Slack, EMail, Text...) specific CVE IDs.

config.toml

[default]
ignoreCves = ["CVE-2016-6313"]

[servers.bsd]
host     = "192.168.11.11"
user     = "kanbe"
ignoreCves = ["CVE-2016-6314"]

Example: IgnoreCves of a container

config.toml

[default]
ignoreCves = ["CVE-2016-6313"]

[servers.cent7]
host     = "192.168.11.11"
user     = "kanbe"

[servers.cent7.containers.romantic_goldberg]
ignoreCves = ["CVE-2016-6314"]

Example: IgnorePkgsRegexp

Define ignorePkgsRegexp in config if you don't want to report(Slack, EMail, Text...) match against the specific regexp google/re2.

[servers.c74]
host     = "192.168.11.11"
user     = "kanbe"
ignorePkgsRegexp = ["^kernel", "^python"]

[servers.c74.containers.romantic_goldberg]
ignorePkgsRegexp = ["^vim"]

Example: GitHub Security Alerts Integration

Usage: Integrate with GitHub Security Alerts

Example: Add optional key-value pairs to JSON

Optional key-value can be outputted to JSON. The key-value in the default section will be overwritten by servers section's key-value. For instance, you can use this field for Azure ResourceGroup name, Azure VM Name and so on.

config.toml

[default]
[default.optional]
key1 = "default_value"
key3 = val3


[servers.bsd]
host     = "192.168.11.11"
user     = "kanbe"
[servers.bsd.optional]
key1 = "val1"
key2 = "val2"

bsd.json

[
  {
    "ServerName": "bsd",
    "Family": "FreeBSD",
    "Release": "10.3-RELEASE",
    .... snip ...
    "Optional": {
        "key1": "val1" ,
        "key2": "val2" ,
        "key3": "val3"
    }
  }
]

Example: Use MySQL as a DB storage back-end

config.toml

[cveDict]
type = "mysql"
url = "user:[email protected](localhost:3306)/dbname?parseTime=true"

[ovalDict]
type = "mysql"
url = "user:[email protected](localhost:3306)/dbname?parseTime=true"

[gost]
type = "mysql"
url = "user:[email protected](localhost:3306)/dbname?parseTime=true"

[exploit]
type = "mysql"
url = "user:[email protected](localhost:3306)/dbname?parseTime=true"

[metasploit]
type = "mysql"
url = "user:[email protected](localhost:3306)/dbname?parseTime=true"

$ vuls report
...

If you get below error message while fetching, define sql_mode.

Error 1292: Incorrect datetime value: '0000-00-00' for column 'issued' at row 1

For details, see TODO

Example: Use PostgreSQL as a DB storage back-end

config.toml

[cveDict]
type = "postgres"
url = "host=myhost user=user dbname=dbname sslmode=disable password=password"

[ovalDict]
type = "postgres"
url = "host=myhost user=user dbname=dbname sslmode=disable password=password"

[gost]
type = "postgres"
url = "host=myhost user=user dbname=dbname sslmode=disable password=password"

[exploit]
type = "postgres"
url = "host=myhost user=user dbname=dbname sslmode=disable password=password"

[metasploit]
type = "postgres"
url = "host=myhost user=user dbname=dbname sslmode=disable password=password"

$ vuls report
...

Example: Use Redis as a DB storage back-end

config.toml

[cveDict]
type = "redis"
url = "redis://localhost/1"

[ovalDict]
type = "redis"
url = "redis://localhost/1"

[gost]
type = "redis"
url = "redis://localhost/1"

[exploit]
type = "redis"
url = "redis://localhost/1"

[metasploit]
type = "redis"
url = "redis://localhost/1"

$ vuls report
...

Example: Use HTTP to access to vulnerability dictionary

config.toml

[cveDict]
type = "http"
url = "http://localhost:1323"

[ovalDict]
type = "http"
url = "http://localhost:1324"

[gost]
type = "http"
url = "http://localhost:1325"

[exploit]
type = "http"
url = "http://localhost:1326"

[metasploit]
type = "http"
url = "http://localhost:1327"

$ vuls report
...