Appcanary is a service which keeps track of which versions of what packages are vulnerable to which security vulnerabilities, so you don't have to.

The Appcanary ruby gem offers a way to automate your vulnerability checks either as part of your Continuous Integration builds, or just programmatically elsewhere. It also provides rake tasks for convenience.

These instructions will get you going on CircleCI with a rails project.

First, add the appcanary gem to your Gemfile:

gem "appcanary"

bundle install it to update your Gemfile.lock.

Add some configuration to your config/initializers/appcanary.rb file:

Appcanary.api_key = ENV["APPCANARY_API_KEY"] || "api key not set"

Now, add the following lines to your circle.yml file:

test:
  # [ ... other dependency bits elided ... ]
  post:
    # outputs CVEs and references
    - bundle exec rake appcanary:check
    # update the appcanary monitor for this app
    - bundle exec rake appcanary:update_monitor

Don't forget to add the APPCANARY_API_KEY environment variable in your project settings in the CircleCI web app. You can find your API key in your Appcanary settings.

Commit and push your changes, and CircleCI should do the right thing.

There are several ways to use the Appcanary gem. The simplest of all is to write a small program, in the context of a Bundler managed project, like this:

require "appcanary"

config = {
  base_uri: "https://appcanary.com/api/v3",
  api_key: "XXXXXXXXXXXXXXXXXXXXXXXXXXX",
  monitor_name: "my_monitor"
}

canary = Appcanary::Client.new(config)

if canary.is_this_app_vulnerable?
  puts "you appear to have your ass in the air"
end

Instead, you can use a global configuration block, in the traditional rails idiom:

Appcanary.configure do |canary|
  canary.api_key = ENV["APPCANARY_API_KEY"] || "api key not set"
  canary.base_uri = "https://appcanary.com/api/v3"
  canary.monitor_name = "my_monitor"
end

This config style is perhaps best suited to use an initializer file in rails projects. We suggest config/initializers/appcanary.rb as a good spot for that.

Here's a static configuration which is a bit less railsish:

Appcanary.api_key = ENV["APPCANARY_API_KEY"] || "api key not set"
Appcanary.gemfile_lock_path = "/path/to/gemfile"

The gem may then be used without instantiating a client, like this:

if Appcanary.is_this_app_vulnerable? :critical
  puts "I see your shiny attack surface! It BIG!"
end

Finally, we provide two rake tasks, which are installed automatically in rails projects. They are as follows:

$ rake -T
...
rake appcanary:check                    # Check vulnerability status
rake appcanary:update_monitor           # Update the appcanary monitor for this project
...

$ rake appcanary:check
CVE-2016-6316
CVE-2016-6317
$ rake appcanary:update_monitor
$

If you're using the rake tasks in a non-Rails environment, you'll need to configure the appcanary gem using the third and final method; a YAML file called appcanary.yml, in your project root. The contents, unsurprisingly, look like this:

api_token: "xxxxxxxxxxxxxxxxxxxxxxxxxx"
base_uri: "https://appcanary.com/api/v3"
monitor_name: "my_monitor"

For Heroku rails deployments, everything should really "just work".

1. Include the appcanary gem in your Gemfile - see previous section.
2. Ensure you have the api_key set to ENV["APPCANARY_API_KEY"] - see previous section.
3. Set the env var like this: heroku config:set APPCANARY_API_KEY=xxxx -a yorapp, where yorapp is replaced with the name of your Heroku application.
4. Once deployed, try heroku run rake appcanary:check to verify your dependencies.
5. Optionally, set up a regular monitor update using the heroku scheduler:
6. heroku addons:create scheduler:standard - creates a new scheduler service instance, attached to your application.
7. heroku addons:open scheduler - opens a browser window on the scheduler service UI.
8. Add a job that executes rake appcanary:update_monitor - the scheduler UI makes how to do this obvious (at the time of writing).

Steps 1 and 2 are exactly as described in previous sections. This should get you going with a rails deployment on Heroku.

As we've seen, you can configure the appcanary gem several different ways. All configurations include the following items however.

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/appcanary/appcanary.rb.