Skip to content
This Zeek package enables file submission to the BluVector Malware Analysis Portal for deep file analysis and metadata.
Zeek
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples
scripts
.gitignore
LICENSE
NOTICE
README.md
bro-pkg.meta

README.md

BluVector File Portal Support

This Zeek package enables Bro 2.5 to submit files to the BluVector Malware Analysis Portal for deep file analysis. Analysis results are logged to bvfileanalysis.log. Before you get started, please see the limitations list at the bottom of this file. See "Getting Started" below to obtain free access credentials for the portal, and install/configure the package.

The following supplemental files are available under the examples directory in the github repo.

  • bvfileanalysis.bro: sample, commented policy file to activate BVFileAnalysis. It includes a commented hook, BVFileAnalysis::file_filter(), that defaults to submitting all extracted files but also shows how to filter based on mime type.

  • bvfileanalysis.sh: bare-bones script to send files directly using a curl command.

Getting Started

Please complete the following steps to integrate the BVFileAnalysis package into your Zeek cluster.

  1. Request Portal Access.
    Please visit BluVector Analysis Trial page and complete the short request form for your free portal access credentials. The credentials will be emailed to you so you can complete the following activation procedure.

  2. Install the BVFileAnalysis package.
    The package can be installed using the Bro Package Manager. Run the following commands to install it under your bro-pkg script_dir, which defaults to <prefix>/share/bro/site. It's best to clone the git repository, which contains example files, and install from it.

    bro-pkg autoconfig # optional, only needed if you haven't used bro-pkg before
    git clone https://github.com/bluvectorcyber/zeek-pkg-fileanalysis
    bro-pkg install zeek-pkg-fileanalysis && bro-pkg unload zeek-pkg-fileanalysis
    
  3. Activate BVFileAnalysis.
    After installing the package, you'll need to provide a policy script to configure and activate it. A sample, commented script is in the git repo you cloned above, at zeek-pkg-fileanalysis/examples/bvfileanalysis.bro.

    1. Copy zeek-pkg-fileanalysis/examples/bvfileanalysis.bro to <prefix>/share/bro/policy/bvfileanalysis.bro, and edit it as follows.

    2. Provide the username and password constants for your portal access credentials, obtained in step one.

    3. By default, all files are submitted. To avoid exhausting your daily quota limit too quickly, modify the BVFileAnalysis::filter_file() hook to choose which files to send.

    4. Examine the other constants in bvfileanalysis.bro for possible changes according to the comments. In particular, you'll need to specify a parameter via the BVFileAnalysis::site_curl_args variable if your https requests go through a proxy. See the bullet under Limitations at the end of this file for a caveat about using a non-transparent proxy with this application.

    5. Add @load bvfileanalysis to <prefix>/share/bro/site/local.bro.

    6. Execute broctl deploy to start sending files to the BluVector File Portal!

Analysis Results Description

The BluVector File Portal response will contain a json string of the file analysis results. That json string response will be written to bvfileanalysis.log. The fields of the json response are described below.

{
  "fileSha256": (string) SHA256 hash of submitted file,
  "confidence": (float) Score, between 0 and 1, indicating likelihood of maliciousness,
  "threshold": (float) A default minimum score at which a file is considered malicious,
  "hectorFileType": (string) Hierarchic MLE file type,
  "malicious": (bool) Whether file is determined to be malicious based on confidence and threshold values,
  "version": (string) MLE version,
  "fileSize": (int) Size of file in bytes,
  "timestamp": (string) ISO-8601 formatted string of file submission time,
  "libmagicString": (string) Output of the Unix file command,
  "bundleID": (string) ID of MLE classifier bundle,
  "classifierID": (string) Classifier used by MLE to score submitted file,
  "elapsedTime": (float) Elapsed analysis time in milliseconds,
  "parserOutput": (object) A mapping of parser types to parser results for the submitted file,
}

The response headers may include the following information, but note the limitation below about using a non-transparent proxy.

  • Possible HTTP response status codes (201 and 429 should be most common) and descriptions:
    • 201: Everything went well, the unmodified analysis output is written to stdout in JSON format
    • 400: Usually means a validation error, i.e. a file wasn't specified
    • 401: Didn't specify username:password
    • 403: The username:password are valid, but aren't entitled
    • 408: We timed out sending the file to Hector, might be too large
    • 413: Hector told us the file is too large explicitly
    • 415: The file type given is "unexpected" (not entirely sure what that means)
    • 422: The file type given is not supported
    • 429: Daily quota exhausted, no more analyses until after midnight UTC
    • 5XX: Portal server error
  • The following headers (with sample values) are returned with responses other than status codes other than 400, 401, 403, and 5XX
    • bv-ratelimit-hector-remaining: 10
    • bv-ratelimit-hector-reset: 2019-10-04T00:00:00+00:00

Limitations

  • This package has only been tested on Bro 2.5.

  • If you configure this package to use a non-transparent proxy, file limit and other status are currently not logged. This information is returned in the portal response headers, and the blank line after the proxy response header causes the rest to be discarded. This means you'll get no indication of problems or file limits unless you manually run curl to see all headers. See zeek-pkg-fileanalysis/examples/bvfileanalysis.sh, which submits a file and stores the response headers in a local file. A transparent proxy should work fine. YMMV.

  • See examples/bvfileanalysis.sh for an example curl command to submit a file.

  • Your access credentials are restricted to 25 file submissions per day. This quota is refreshed at midnight UTC. Please contact info@bluvector.io to request a higher limit.

  • BVFileAnalysis works best with live traffic. Unfortunately, it doesn't work by ingesting pcap files via `bro -r . If you have already extracted files, check out our python-based submit-files repo to submit them via the command line.

You can’t perform that action at this time.