Velociraptor hunts for evil...
Switch branches/tags
Clone or download
Permalink
Failed to load latest commit information.
actions Added file upload for event monitoring flow. Nov 13, 2018
api Rewrite pslist for windows. Nov 8, 2018
artifacts Added file upload for event monitoring flow. Nov 13, 2018
bin Rewrite pslist for windows. Nov 8, 2018
config Event monitoring framework to collect process execution logs. Oct 24, 2018
constants Event monitoring framework to collect process execution logs. Oct 24, 2018
crypto Rewrite pslist for windows. Nov 8, 2018
datastore Rewrite pslist for windows. Nov 8, 2018
debian Added a few more artifacts. Aug 16, 2018
events Event monitoring framework to collect process execution logs. Oct 24, 2018
executor Event monitoring framework to collect process execution logs. Oct 24, 2018
file_store Rewrite pslist for windows. Nov 8, 2018
flows Added file upload for event monitoring flow. Nov 13, 2018
glob Prepare release 0.2.4 Sep 30, 2018
grpc_client Rewritten the comms subsystem. Aug 30, 2018
gui Event monitoring framework to collect process execution logs. Oct 24, 2018
http_comms Rewrite pslist for windows. Nov 8, 2018
logging Initial implementation of windows process execution log collection. Oct 10, 2018
proto Rewrite pslist for windows. Nov 8, 2018
responder Implemented Log in flows. Jul 6, 2018
scripts Added a debian packaging system. May 21, 2018
server Initial implementation of windows process execution log collection. Oct 10, 2018
templates Build debian package templates. May 19, 2018
test_data Rewritten the comms subsystem. Aug 30, 2018
testing Rewritten the comms subsystem. Aug 30, 2018
third_party/cache Implemented the GRR encryption algorithm. Apr 14, 2018
tools Added Windows user() VQL plugin. Aug 26, 2018
urns Reorganized AFF4 space to have clients in their own prefix. Sep 2, 2018
users Implemented user authentication and notifications. Aug 10, 2018
utils Implement Lstat for registry accessor. Sep 29, 2018
vql Added file upload for event monitoring flow. Nov 13, 2018
vql_plugins Added an event viewer parser and watcher. Oct 31, 2018
.gitignore Refactor accessor API to allow root containing path sep. Sep 25, 2018
Gopkg.lock Added dirname and basename functions. Nov 10, 2018
Gopkg.toml Implemented Yara VQL plugins. Sep 25, 2018
LICENSE Add LICENSE May 6, 2018
Makefile Rewrite pslist for windows. Nov 8, 2018
README.md Rewrite pslist for windows. Nov 8, 2018
appveyor.yml Added more windows tests. Sep 30, 2018
docs.go Added more client actions and VQL plugins. May 6, 2018
make_proto.sh Initial implementation of windows process execution log collection. Oct 10, 2018

README.md

Velociraptor - Endpoint visibility and collection tool.

Velociraptor is a tool for collecting host based state information using Velocidex Query Language (VQL) queries.

Velociraptor is loosely based on Google's GRR technologies but is a re-implementation and redesign focusing on ease of use, scalability and flexibility.

To learn more about Velociraptor, read about it on our blog:

https://velociraptor-blog.velocidex.com

Quick start

  1. Download the binary from the release page.

  2. You need to generate a server config file. This will generate new key material:

    $ velociraptor config generate > /etc/velociraptor.config.yaml
  3. Edit the config file and update any settings. In particular you would probably need to update the following:

    • Client.server_urls - the public-facing URLs to connect to the server.

    • Datastore.location and Datastore.filestore_directory - where to store files on the server.

  4. To be able to log into the GUI you will need to make a user account with password.

    $ velociraptor --config /etc/velociraptor.config.yaml user add my_user_name
  5. Start the server:

    $ velociraptor --config /etc/velociraptor.config.yaml frontend
  6. Point a browser at the GUI port that you set in the config file. You should be able to log in with the password set earlier.

  7. Generate a client config (this is just the client part of the server config you made before - it contains no secrets and can be installed on clients.):

    $ velociraptor --config /etc/velociraptor.config.yaml config client > client.conf.yaml
  8. Launch the client on any system with this client config file.

    $ velociraptor --config client.conf.yaml client
  9. You should be able to search for the client in the GUI, browse VFS, download files etc.

NOTE: You may omit the --config flag in the following cases:

  • If the VELOCIRAPTOR_CONFIG environment variable exists, Velociraptor will read its configuration from there.
  • If you embed the configuration into the binary (using velociraptor config repack as below), Velociraptor will magically know its own configuration without reading it from a file at all.

NOTE: If you embed the server's config into the binary then the binary will have key material in it - this could pose a security issue if the binary itself is leaked. It's OK to embed client config in the client because client configs have no secrets.

To create a windows executable:

  1. Embed the client config in the binary. This makes the binary self contained for your particular installation. It is therefore very easy to install:

    $ velociraptor config repack --exe velociraptor_windows.exe client.config.yaml my_velociraptor.exe

    Where velociraptor_windows.exe is the Windows binary release for Velociraptor.

  2. If you need to sign the binary, now is the time. The signature will cover the embedded configuration as well. It is possible to update the embedded config but this will invalidate the signature.

  3. On a windows system you can now install the service:

    $ my_velociraptor.exe service install
    INFO:2018/08/28 00:18:19 Stopped service Velociraptor
    INFO:2018/08/28 00:18:20 Copied binary to C:\Program Files\Velociraptor\Velociraptor.exe
    INFO:2018/08/28 00:18:20 Installed service Velociraptor
    INFO:2018/08/28 00:18:21 Started service Velociraptor

This will copy the binary into the install_dir specified in the config file, create and start the service.

Running Velociraptor locally.

Velociraptor is also useful as a local triage tool. In particular you might find Velociraptor's artifacts especially useful for quickly capturing important information about a running system. You can collect artifacts by using the "artifacts collect" command:

```bash
$ velociraptor artifacts list
INFO:2018/08/20 22:28:56 Loaded 18 built in artifacts
INFO:2018/08/20 22:28:56 Loaded 18 artifacts from artifacts/definitions/
Linux.Applications.Chrome.Extensions
Linux.Applications.Chrome.Extensions.Upload
Linux.Applications.Docker.Info
Linux.Applications.Docker.Version
Linux.Debian.AptSources

$ velociraptor artifacts list -v Linux.Debian.AptSources
.... displays the artifacts

$ velociraptor artifacts collect Linux.Debian.AptSources
... Collects all the named artifacts
```

Explore more of Velociraptor's options using the -h flag.

Building from source.

To build from source, make sure you have a recent Golang installed: ```bash $ go get -u www.velocidex.com/golang/velociraptor $ cd $GO_PATH/go/src/www.velocidex.com/golang/velociraptor/

# This will download go dependencies.
$ dep ensure

# This will build the GUI elements:
$ cd gui/static/
$ npm install
$ gulp compile
$ cd -

# This builds a release (i.e. it will embed the GUI files in the
# binary). If you dont care about the GUI a simple "make" will
# build a bare binary.
$ make release
$ make windows
```

If you want to rebuild the protobuf you will need to install protobuf compiler:

$ wget https://github.com/protocolbuffers/protobuf/releases/download/v3.6.1/protoc-3.6.1-linux-x86_64.zip
$ unzip protoc-3.6.1-linux-x86_64.zip
$ sudo mv include/google/ /usr/include/
$ sudo mv bin/protoc /usr/bin/
$ go get github.com/golang/protobuf/protoc-gen-go/
$ go install github.com/golang/protobuf/protoc-gen-go/
$ go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
$ go install github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
$ ./make_proto.sh

Getting help

Questions and feedback are welcome at velociraptor-discuss@googlegroups.com

File issues on https://gitlab.com/velocidex/velociraptor

Read more about Velociraptor on our blog:

https://velociraptor-blog.velocidex.com/