How to Get Started
We built the Spectral platform from the ground up to have fantastic developer experience (DX). Spectral Scan is a single self-contained binary, that's easy to get and use.
Your first scan
You can get Spectral in one of the following ways, for your convenience:
Homebrew on mac:
brew tap spectralops/tap && brew install spectral
Or, universal installer for mac/Linux:
curl -L https://<YOUR_SPECTRAL_DOMAIN>/latest/x/sh | sh
replace <YOUR_SPECTRAL_DOMAIN>
with the domain you use to login to SpectralOps (get.spectralops.io, app.spectralops.io etc)
And for Windows PowerShell:
iwr https://<YOUR_SPECTRAL_DOMAIN>/latest/ps1 -useb | iex
All of the above are great. Pick the one you like ๐ค
Enterprise customers can use their DSN to get the Spectral enterprise offering, for example:
curl -L https://<YOUR_SPECTRAL_DOMAIN>/latest/sh?dsn=<YOUR_DSN> | sh
Spectral offers several scanning engines. You can read all about it in the Products section.
We'll focus on the Spectral Secret Scanning for this example, so go a head and make your first scan:
$ mkdir spectral-test && cd spectral-test
$ $HOME/.spectral/spectral scan --dsn <YOUR_DSN>
โ no matches found
scanned 0 bytes and 0 files in 2ms
As a security best-practice, you should never run
curl | sh
blindly. Feel free to inspect our install script (it's a shell script) before running. We also recommend using our very own preflight to verify checksums.
๐ฆธโโ๏ธ You're good to go! Looks like everything downloaded right, and things are running!
Your first match
Assuming you're still in spectral-test
, let's create a dummy secret:
$ echo AKIAIOSFODNN7EXAMPLX > foo.txt
$ $HOME/.spectral/spectral scan
/Users/superhero/spectral-test/foo.txt
0:20 Error Visible AWS Key CLD001
We see our match. We have our file, a location (0:20
), severity (Error
), description and detector code (CLD001
).
Spectral is secure by default
We never dump the actual secret or key to the console, or anywhere. If you want to see it, add a
SPECTRAL_SHOW_MATCH=1
environment flag before running.
$ $HOME/.spectral/spectral scan
...
[your-project] SVC006 - Exposed PubNub Secret on Client Side App
- res/values/strings.xml
Kicking the tires ๐ฅ
To get an idea of the amount of stacks Spectral can analyze, you can use our codesec-goat
repo.
What's a "goat" project?
A common saying is that if your fence won't hold water, it won't hold a goat. Animals are very creative, and will find a way around your barriers. In the same funny analogy, a goat repo demonstrates creativity and deliberate security issues that you might not expect.
Assuming you unzipped codesec-goat
somewhere, let's run Spectral scan:
$ cd codesec-goat
$ $HOME/.spectral/spectral scan
โ spectral-goat git:(master) spectral scan
__ .__
___________ _____ ______/ |_____________ | |
/ ___\____ \/ _ / ___\ __.| __/\__ \ | |
\___ \| |_> \ ___\ \___| | | | / __ \| |_
/______| __/ \_____\_____|__| |__| /______|___/ops.io
|__|
Spectral: 1.9.131 (1602)
OS: macos (x86_64)
is_audit: No
DSN: Yes (from param/env)
mode: interactive
is_public: n/a
repo: https://github.com/spectral-corp/spectral-goat
branch: master
remote_cfg: Yes
High: Visible Google API Key [CLD004]
โญโ[src/infra/google-api.json:24:27]
โ
24 โ "current_key": "AIzaSyAM*******************************"
ยท โโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโโโโโโโโโ Visible Google API Key
โโโโโฏ
Medium: Visible Google cloud host [CLD030]
โญโ[src/infra/google-api.json:18:25]
โ
18 โ "client_id": "344570128040-0a*********************************************************",
ยท โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Visible Google cloud host
โโโโโฏ
Medium: Visible Google cloud host [CLD030]
โญโ[src/infra/google-api.json:31:29]
โ
31 โ "client_id": "344570128040-0a*********************************************************",
ยท โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Visible Google cloud host
โโโโโฏ
High: Google Client ID URL [GOOG001]
โญโ[src/infra/google-api.json:18:25]
โ
18 โ "client_id": "344570128040-0a*********************************************************",
ยท โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Google Client ID URL
โโโโโฏ
High: Google Client ID URL [GOOG001]
โญโ[src/infra/google-api.json:31:29]
โ
31 โ "client_id": "344570128040-0a*********************************************************",
ยท โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Google Client ID URL
โโโโโฏ
High: Visible Private Key [KEYS002]
โญโ[src/infra/rsa.key:1:1]
โ
1 โ โญโโถ -----BEGIN RSA PRIVATE KEY-----
โฎ โฎ
27 โ โโโถ *****************************
ยท โ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Visible Private Key
โโโโโฏ
High: Visible Private Key [KEYS002]
โญโ[src/infra/id_rsa:1:1]
โ
1 โ โญโโถ -----BEGIN OPENSSH PRIVATE KEY-----
โฎ โฎ
38 โ โโโถ *********************************
ยท โ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Visible Private Key
โโโโโฏ
High: MemCached configured to run as root [MEMC002]
โญโ[src/infra/memcache/memcached.conf:30:1]
โ
30 โ *******
ยท โโโโฌโโโ
ยท โฐโโโโโ MemCached configured to run as root
โโโโโฏ
Medium: MySQL config file contains a visible report password [MYSQL003]
โญโ[src/infra/mysql/mysqld.cnf:24:21]
โ
24 โ report-password = **** # bad password
ยท โโโฌโ
ยท โฐโโโ MySQL config file contains a visible report password
โโโโโฏ
Medium: Redis configuration include one or more users with a visible password [REDIS001]
โญโ[src/infra/redis/redis.conf:16:31]
โ
16 โ user shai on +@all -DEBUG ~* >************ -@all
ยท โโโโโโโฌโโโโโ
ยท โฐโโโโโโโ Redis configuration include one or more users with a visible password
โโโโโฏ
Medium: Redis configured to worldwide listening [REDIS003]
โญโ[src/infra/redis/redis.conf:8:1]
โ
8 โ bind *****************
ยท โโโโโโโโโโโโฌโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโ Redis configured to worldwide listening
โโโโฏ
Informational: Potential cryptographic key bundle file [SENF006]
โญโ[/Users/jenia/dev/spectral-goat/src/notebook/docs/source/ipython_security.asc]
โ
โโโโโฏ
Medium: Google Services JSON File [SENF086]
โญโ[/Users/jenia/dev/spectral-goat/src/infra/google-api.json]
โ
โโโโโฏ
Medium: Found a SQLite database file [SENF106]
โญโ[/Users/jenia/dev/spectral-goat/src/notebook/notebook/tests/test_hist.sqlite]
โ
โโโโโฏ
Informational: Exposed Sentry DSN [SVC016]
โญโ[src/frontend/sentry.js:9:9]
โ
9 โ dsn: 'https://3427253**********************************************************',
ยท โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ Exposed Sentry DSN
โโโโฏ
High: Visible Terraform Azure Database password [TF010]
โญโ[src/multicloud/terraform/azure/main.tf:12:35]
โ
12 โ administrator_login_password = "4-v3r*****************"
ยท โโโโโโโโโโโโฌโโโโโโโโโโ
ยท โฐโโโโโโโโโโโโ Visible Terraform Azure Database password
โโโโโฏ
Medium: Visible Terraform Azure Database username [TF011]
โญโ[src/multicloud/terraform/azure/main.tf:11:35]
โ
11 โ administrator_login = "*************"
ยท โโโโโโโฌโโโโโโ
ยท โฐโโโโโโโโ Visible Terraform Azure Database username
โโโโโฏ
โ found 17 matches
scanned 10515636 bytes and 557 files in 507ms
You'll see a wealth of findings ranging around the following topics:
- Sensitive data
- Credentials and access controls
- Misconfiguration
- Tech stack bad practices
๐ฆธโโ๏ธ Human error is, well, complicated. You may detect SQL injection, update libraries every day, still -- takes one innocent mistake to expose your team to unneeded risk.
Our idea is: we build an understanding of everything that can lead to security minded human errors, and poses a high risk. Then we look for it, detect it, and help you block and mitigate it.
Make it stick
Now that you've seen what Spectral can do, you can plug it into your development processes so that you're safe all the time. Like any new process for a dev team, we need to make the process stick.
One of the most recommended places to integrate Spectral to is your CI.
Never hold up a build
We build Spectral for performance. Every day. That's actually a business KPI of ours. Spectral scans an average sized repo in a second. Thanks to Rust and our low-level engineers, we're very happy.
Let's see how Spectral works in CircleCI (we support every popular CI there is today):
Before
version: 2
jobs:
build:
docker:
- image: circleci/node:latest
steps:
- checkout
- run: yarn test
Now you need to add your TEAM_KEY
and your SPECTRAL_DSN
to CircleCI (look here for how to do that). And use this configuration:
version: 2
jobs:
build:
docker:
- image: circleci/node:latest
steps:
- checkout
- curl -L 'https://get.spectralops.io/latest/sh?key=${TEAM_KEY}' | sh
- $HOME/.spectral/spectral run
- run: yarn test
As a security best-practice, you should never run