Telescope
This project is under active development towards a stable release. Warning: master
is subject to breaking changes.
Telescope used to monitor websites. Much like a telescope, it can crudely see things from far away. It can watch for new vulnerabilities, unexpected changes, outages, and more. It integrates with Sendgrid to send email alerts. Future releases aim to support integrations for:
- Slack
- Text via Email
- Twillio (Text)
- Twillio (Call)
- Configurable webhook
It works by fetching configured URIs at their configured time, storing the request output and other associated data, and running regexes against those configured attributes. If a regex is matched against a particular attribute, the alert is triggered.
Usage
Telescope is a binary designed to be run in a container (modularsystems/telescope:latest), so you can either run the container, or deploy it with your orchestrator of choice.
Here are some examples on how you can run it:
Cron
Cron is a popular favorite for task automation. You can use this container with cron by creating your config locally. Then, pass in your configuration to the container by a volume mount.
Example /etc/telescope/config.yaml
:
alerts:
- name: Vulnerability Report
Configuration:
Secrets data is passed via environment variables. Here is what can be configured by environment variables:
Environment Variable | Description |
---|---|
SENDGRID_API_KEY | Configure your sendgrid token to receive email alerts |
SENDGRID_SENDER_NAME | Your sendgrid verified user's name See: Sendgrid sender identity |
SENDGRID_SENDER_EMAIL | Your sendgrid verified user's email address See also: Sendgrid sender identity |
WPVULNDB_API_KEY | Configure your wpvulndb token for richer wordpress vulnerability detection, you can get one free here |
The following flags exist to help you configure the application:
flag | description |
---|---|
--debug | turn on debug logging |
--config | path to configuration on the filesystem. default: /etc/telescope/config.yaml |
Configuring Alerts
Alert configuration is done in YAML. An example alert might look like this:
alerts:
- name: Non 200 Returned from mywebsite.com
uris:
- https://mywebsite.com
- https://zombo.com
- https://www.zombo.com
scanner: HTMLScan
attribute: "return code"
regex: "^((?!.*200.*).)*$"
every: 5m
send: text
page:
- "555-555-5555"
- "5555555555"
- name: Plugin Vulnerability Discovered
scanner: WPScan
uris:
- https://www.zombo.com
- https://zombo.com
send: email
page:
- "Dev Null dev@null"
- "dead beef dead@beef"
regex: "Plugin.Vulernability.Discovered"
timed: "13:00 UTC"
Backlog
- Refactor daemon loop to iterate through urls instead of two separate loops iterating through all scans and alerts. Using Urls could allow o(n) to be reduced to the minimal amount of operations but also reduce work. This can be done by scanning once, then save the output to all relative jobs.
- Adequate testing is missing:
- mock an http server for network scan testing
- add alert testing where possible
- stub out configuration tests to catch edge cases, such as sendTo parsing
- Documentation can be improved
- Redesign data models. I suspect there are better ways to organize this data
- Export basic metrics like time per cycle, requests handled, error rate, etc