{"id":19149532,"url":"https://github.com/alphasoc/asoc-zeek","last_synced_at":"2026-06-17T03:32:12.753Z","repository":{"id":85395340,"uuid":"438237099","full_name":"alphasoc/asoc-zeek","owner":"alphasoc","description":null,"archived":false,"fork":false,"pushed_at":"2022-01-28T14:08:07.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T12:51:24.351Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alphasoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-14T12:02:53.000Z","updated_at":"2022-02-07T14:15:49.000Z","dependencies_parsed_at":"2023-03-04T05:00:28.730Z","dependency_job_id":null,"html_url":"https://github.com/alphasoc/asoc-zeek","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alphasoc/asoc-zeek","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphasoc%2Fasoc-zeek","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphasoc%2Fasoc-zeek/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphasoc%2Fasoc-zeek/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphasoc%2Fasoc-zeek/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alphasoc","download_url":"https://codeload.github.com/alphasoc/asoc-zeek/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphasoc%2Fasoc-zeek/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34433085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T08:08:34.718Z","updated_at":"2026-06-17T03:32:12.743Z","avatar_url":"https://github.com/alphasoc.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# asoc-zeek\n\nThis project provides instructions (this README) for configuring the network monitoring\ntool [Zeek](https://zeek.org), to capture and relay network telemetry to AlphaSOCs\nAnalytics Engine (AE).  Once delivered to AE, telemetry is analyzed for a wide range of\npotential network threats.  These threats then trigger detections which can be viewed in\nthe AlphaSOC Console.  To further simplify this process, a BASH script, `bin/asoc-zeek`,\nis also provided.  `bin/asoc-zeek` generates a custom Zeek config file, starts Zeek, and\nperforms some basic cleanup of Zeek logs on exit.\n\nThis guide will cover the steps needed to register with AlphaSOCs Console, manual Zeek\nconfiguration and startup, as well as a quick introduction to `bin/asoc-zeek`.\n\nFor further insight into how Zeek works, please visit the Zeek homepage linked above.  For\ndetails about AE, visit:\n[AlphaSOCs Analytics Engine](https://docs.alphasoc.com/ae/architecture/).\n\n## Who is this for?\n\nIf you're an existing AlphaSOC customer and would like to try Zeek as a network monitoring\ntool, this is for you.\n\nIf you're not a customer, but are curious about the kinds of threats that AlphaSOC can help\nyou detect on your network, this is for you as well.\n\n## AlphaSOC Registration\n\nSince this guide focuses on setting up Zeek to work with AE, an AlphaSOC account is\nneeded to get started.  If you don't have an account, please visit\n[Demo | AlphaSOC](https://alphasoc.com/demo/) and register for one.  The registration\nwill grant you a **free**, 30 day demo of AlphaSOC services.  You'll receive an email\nwith a verification link and an **Organization ID**.  Be sure to verify the account\nbefore continuing.\n\nOnce you have an account, please visit: [Console | AlphaSOC](https://console.alphasoc.net)\nand sign in with your credentials.  Your **Organization ID** (also known as a\n**Workspace ID**) will be found at the top of https://console.alphasoc.net/credentials\nCopy it to your clipboard for later use.\n\n**NOTE:** If you're an AlphaSOC developer using the staging variant of AlphaSOC services,\nsee the [Developers](#developers) section before continuing on.\n\n## SSH/Authentication\n\nZeek will be configured to use SFTP (with SSH-key authentication) in order to upload\ntelemetry to AlphaSOC.  Thus, you will want to generate an SSH-key pair (without a\npasshphrase, unless you wish to take the necessary steps to use something like `ssh-agent)\nand upload the public key to the *Credentials* page\n(https://console.alphasoc.net/credentials) using the *SSH Keys* dialog.  Ensure that the\nprivate key is kept in a readable location on the system from which you will run Zeek,\nand also ensure that it will be used when communicating with AlphaSOC.  This can be done\nby modifying `~/.ssh/config` and adding the following:\n\n    Host sftp.alphasoc.net\n      HostName sftp.alphasoc.net\n      IdentityFile /path/to/SSH-keys/your-key-file\n\n**NOTE:** Because Zeek captures packets from a given interface, Zeek must be run by a user\naccount with the appropriate permissions.  On Linux systems with kernels supporting\ncapability bits (ie. `CAP_NET_RAW`), this can be a regular user account, provided the Zeek\nbinary has been given the appropriate permission (more on this later).  On BSD systems\nor Linux systems without capability bit support, it will be easiest to run Zeek as root\nor via `sudo`.  In such cases, the generated SSH keys and modified config should reside\nin root's home directory (ie. `/root/.ssh`).  On OSX, you would use `sudo`, but the SSH\nkeys and config would remain in your home directory.  Lastly, BSD systems (including OSX)\ncan be configured to allow a non-root user to access the packet capture device (`/dev/bpf`)\nthus allowing them to run programs such as Zeek.  This is done by adding the desired user\nto a group which has been given access to `/dev/bpf`.  Exact instructions on how to do this\nare beyond the scope of this guide, but are readily available online.\n\n## Installing Zeek\n\nThis guide has been tested with Zeek version 4.1.1.  To install Zeek, visit\nhttps://zeek.org/get-zeek/, and follow the instructions for your system.  Once installed,\nmake sure to add the installation destination to your user path.  Again, this will be\nthe user that will run Zeek.  For example, if Zeek has been installed to `/opt/zeek/bin`,\nadd the path via:\n\n    $ export PATH=$PATH:/opt/zeek/bin\n\nYou may also add this to your shell's startup script.\n\n## Running Zeek\n\n### Automatically via the `asoc-zeek` Script\n\nIf you want to try an automated approach for generating a config file and starting Zeek,\ndownload `asoc-zeek`, found under this projects `bin/` directory, to a location readable\nby the user account that will be used to run Zeek.  Then, determine on which interface\nyou want Zeek to capture packets (ie. via `ip`/`ifconfig`/etc) and finally, where INTF\nis the capture interface, run:\n\n    $ /path/to/asoc-zeek -i INTF -o ORGANIZATION_ID\n\nFor additional usage documentation, see: `/path/to/asoc-zeek --man` and\n`/path/to/asoc-zeek --help`\n\nAssuming all went well and `asoc-zeek`, along with Zeek, are running, you can move onto\n[Testing](#testing-alphasoc-threat-detection).\n\n### Manually\n\nZeek deposits its log files in the current working directly.  To keep things clean, it's\nbest to create a Zeek working directory, and change to that directory before continuing.\nLet's assume that the working directory you've created and changed to is `~/.asoc/zeek`.\n\nCreate an empty file to house your Zeek config.  You can call this file anything you like\n(ie. `~/.asoc/zeek/myconfig.zeek`).  Now, copy-and-paste and template below into your\n`myconfig.zeek`.\n\n    module SSL;\n    export {\n        redef record Info += {\n            cert_hash: string \u0026log \u0026optional;\n        };\n    }\n    hook ssl_finishing(c: connection) \u0026priority=5\n        {\n        if ( c$ssl?$cert_chain \u0026\u0026 |c$ssl$cert_chain| \u003e 0 \u0026\u0026 c$ssl$cert_chain[0]?$x509 )\n            {\n            c$ssl$cert_hash = c$ssl$cert_chain[0]$sha1;\n            }\n        }\n\n    event zeek_init()\n    {\n        Log::add_filter(Conn::LOG, [$name=\"log-conn\", $path=\"conn_logs\", $writer=Log::WRITER_ASCII,\n               $interv=30sec, $postprocessor=Log::sftp_postprocessor]);\n        Log::sftp_destinations[Log::WRITER_ASCII,\"conn_logs\"] = set([$user=\"ORGANIZATION_ID\",$host=\"sftp.alphasoc.net\",$host_port=2222,$path=\"conn_logs_path\"]);\n\n        Log::add_filter(DNS::LOG, [$name=\"log-dns\", $path=\"dns_logs\", $writer=Log::WRITER_ASCII,\n               $interv=30sec, $postprocessor=Log::sftp_postprocessor]);\n        Log::sftp_destinations[Log::WRITER_ASCII,\"dns_logs\"] = set([$user=\"ORGANIZATION_ID\",$host=\"sftp.alphasoc.net\",$host_port=2222,$path=\"dns_logs_path\"]);\n\n        Log::add_filter(HTTP::LOG, [$name=\"log-http\", $path=\"http_logs\", $writer=Log::WRITER_ASCII,\n               $interv=30sec, $postprocessor=Log::sftp_postprocessor]);\n        Log::sftp_destinations[Log::WRITER_ASCII,\"http_logs\"] = set([$user=\"ORGANIZATION_ID\",$host=\"sftp.alphasoc.net\",$host_port=2222,$path=\"http_logs_path\"]);\n\n        Log::add_filter(SSL::LOG, [$name=\"log-ssl\", $path=\"ssl_logs\", $writer=Log::WRITER_ASCII,\n               $interv=30sec, $postprocessor=Log::sftp_postprocessor]);\n        Log::sftp_destinations[Log::WRITER_ASCII,\"ssl_logs\"] = set([$user=\"ORGANIZATION_ID\",$host=\"sftp.alphasoc.net\",$host_port=2222,$path=\"ssl_logs_path\"]);\n    }\n\nUsing your favourite text editor, replace all instances of *ORGANIZATION_ID* with your actual organization id.\n\nBefore going any further, make sure your user account (root or otherwise) can authenticate\nwith AlphaSOC.  To do so, run:\n\n    $ ssh -p 2222 ORGANIZATION_ID@sftp.alphasoc.net\n\nIf you see output such as `Permission denied (publickey)`, check that the correct SSH\npublic key has been uploaded to https://console.alphasoc.net/credentials, and that you\nare running the SSH command above from the correct user account.  If you still encounter\nthis problem, read through [SSH/Authentication](#ssh/authentication) carefully to make\nsure that your SSH configuration is correct.\n\nIf you're running a Linux distribution with kernel support for capability bits, and you\nwant to run Zeek as a non-root user, you will need to add the appropriate capabilities to\ntwo Zeek executables (`zeek` and `capstats`).  To do so, as root or via `sudo`, run:\n\n    for cmd in zeek capstats; do\n        sudo setcap cap_net_raw=eip $(which \"$cmd\")\n    done\n\nSelect the network interface on which you want Zeek to capture packets\n(ie. via `ip`/`ifconfig`/etc) and, where INTF is the capture interface,\nrun Zeek as the appropriate user:\n\n    $ zeek -i \"INTF\" -p \".\" -U \".status\" \"myconfig.zeek\"\n\nYou should see `listening on INTF`.  When traffic is generated, you will also see a message\nindicating connection, dns, ip, ssl and/or http logs are being sent to AlphaSOC.\n\nAssuming all went well and Zeek is running, you can move onto\n[Testing](#testing-alphasoc-threat-detection).\n    \n## Testing AlphaSOC Threat Detection\n\nWith Zeek running (either manually, or via `asoc-zeek`) and sending telemetry to AlphaSOC,\nyou can now begin generating some simulated, malicious traffic, in order to see the kinds\nof network threats AlphaSOC detects.  The simplest way to generate such traffic, is to\ndownload AlphaSOCs [Network Flight Simulator](https://github.com/alphasoc/flightsim)\nand run the suite of simulations on the system where Zeek is capturing packets.  You can\nbuild `flightsim` from source (a recent Go compiler will be needed), or download one of\nbinary packages from the\n[latest release](https://github.com/alphasoc/flightsim/releases/latest).\n\nOnce installed, alongside Zeek, start with:\n\n    $ /path/to/flightsim -h\n\nTo see a list of simulations that can be run, try:\n\n    $ /path/to/flightsim run -h\n\nTo run all available modules, run:\n\n    $ /path/to/flightsim run\n\nFinally, visit [Console | AlphaSOC](https://console.alphasoc.net/) and in the *Dashboard*\nan overview of detected network threats should be availalbe.  For a more detailed view,\nvisit https://console.alphasoc.net/detections\n\n## Shutting Down Zeek\n\nIf you started Zeek with `asoc-zeek`, you may simply CTRL-C/kill the `asoc-zeek` process.\nZeek log files will be removed from the working directory, leaving behind the automatically\ngenerated config, `stdout.log` and `stderr.log`.  These files are purposefully left behind.\n\nIf you started Zeek manually, CTRL-C/kill the Zeek process.  Log file cleanup is left up\nto the user.\n\n## Final Notes\n\nIf you have any questions, hit any bugs or discrepancies in the documentation, please\nreach out to us on [TODO link to github]() by filing an issue.\n\n## Developers\n\nIf you're an AlphaSOC developer using staging variants of AlphaSOC services, replace\nall instances of alphasoc.net with staging.alphasoc.net in your configurations and\nConsole URLs.  If you plan on using the `asoc-zeek` BASH script, run it with '-s'.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphasoc%2Fasoc-zeek","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falphasoc%2Fasoc-zeek","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphasoc%2Fasoc-zeek/lists"}