This add-on is operated by Sqreen Inc.

Real-time security monitoring and protection made easy

Last updated 12 May 2020

Sqreen is a unified platform to secure web apps. Thanks to Sqreen, you can easily integrate security into your web apps with extensible modules covering application vulnerabilities or user protection.

Built with developers in mind, Sqreen provides stack traces and other actionable information to help you remedy security issues quickly and easily. Get real-time security monitoring for your Heroku app and protect your app from malicious activities and attacks. Extend your application security with customizable security protections.

The Sqreen client library runs alongside your application code and introduces no network latency. Using Sqreen doesn’t require code modification nor traffic redirection.

Sqreen client libraries are available for Ruby, Python, Node.js, Java, PHP and soon GoLang.

Provisioning the add-on

Sqreen can be added to any Heroku application via the CLI:

$ heroku addons:create sqreen
-----> Adding sqreen to sharp-mountain-4005... done, v18 (free)

The SQREEN_TOKEN config var is set automatically for your app when you provision the add-on. It is the credential required to access Sqreen services.

When using Sqreen with Heroku, you should use config vars to configure Sqreen.

Using Sqreen with Ruby

Sqreen is compatible with the most popular Ruby web frameworks. See our Ruby agent compatibility documentation section to confirm it is compatible with your app.

If you have a Ruby on Rails app, add the following gem to your Gemfile:

gem 'sqreen'

Then update your app’s dependencies by running bundle install.

The SQREEN_TOKEN config var is set automatically for your app when you provision the add-on. It is the credential required to access Sqreen services.

For more information about configuring the Sqreen client library, see the Advanced Configuration in Ruby documentation section. You should use the config vars to configure Sqreen.

If your application uses the Devise framework, Sqreen automatically detects and monitors user accounts with the DatabaseAuthenticatable strategy. You can also track your user accounts using our SDK.

Using Sqreen with Python

Sqreen is compatible with the most popular Python web frameworks. See our Python agent compatibility documentation section to confirm it is compatible with your app.

First, install the Sqreen Python client library by adding it in your requirements.txt file.

Then, in your application’s root directory, modify your application file (typically wsgi.py or app.py) by adding the following line of code to the very top:

import sqreen
sqreen.start()

You can also require it directly from your Procfile: web: ... sqreen-start ...

The SQREEN_TOKEN config var is set automatically for your app when you provision the add-on. It is the credential required to access Sqreen services.

For more information about configuring the Sqreen client library, see the Advanced Configuration in Python documentation section.

When using Sqreen with Heroku, you should use config vars to configure Sqreen.

Sqreen automatically detects and monitors user accounts for Python applications running Django 1.6 and later. You can also track your user accounts using our SDK.

Using Sqreen with Node.js

Sqreen is compatible with the most popular Node.js web frameworks. See our Node.js agent compatibility documentation section to confirm it is compatible with your app.

Install the Sqreen Node.js client library with the following command:

$ npm install --save sqreen

Then edit your main script and require the Sqreen client library first, at the top (before New Relic if you are using it):

require('sqreen');

The SQREEN_TOKEN config var is set automatically for your app when you provision the add-on. It is the credential required to access Sqreen services.

For more information on configuring the Sqreen client library, see the Advanced Configuration in Node.js documentation section. You should use the config vars to configure Sqreen.

Sqreen automatically detects and protects user accounts for Node.js apps which use either passport-local version 1.0 or later or passport-http version 0.3 or later for authentication. You can also track your user accounts using our SDK.

Using Sqreen with Java

Sqreen is compatible with the most popular Java web frameworks. See our Java agent compatibility documentation section to confirm it is compatible with your app.

It requires multiple steps :

• add sqreen.jar, either using Maven, Gradle or directly in your repository
• modify Java command line parameters
• set your Sqreen token through Heroku environment variables

Adding sqreen.jar to your project

Using Maven

In pom.xml, add to plugins :

<!-- download latest sqreen agent -->
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>wagon-maven-plugin</artifactId>
  <version>1.0</version>
  <executions>
    <execution>
      <id>download-sqreen</id>
      <phase>package</phase>
      <goals>
        <goal>download-single</goal>
      </goals>
      <configuration>
        <url>https://download.sqreen.io</url>
        <fromFile>java/sqreen.jar</fromFile>
        <toFile>${project.build.directory}/../sqreen.jar</toFile>
      </configuration>
    </execution>
  </executions>
</plugin>

This will download the latest version of Java agent on each deploy. If you want to use a fixed version <version>, replace java/sqreen.jar with java/sqreen-<version>.jar.

Using Gradle

In build.gradle add

plugins {
    id "de.undercouch.download" version "3.4.3"
}

task downloadSqreen(type: Download) {
    src 'https://download.sqreen.io/java/sqreen.jar'
    dest "$buildDir/../sqreen.jar"
    onlyIfModified false
}

// download sqreen agent at stage configuration used by heroku
stage.dependsOn(dowloadSqreen)

This will download the latest version of Java agent on each deploy. If you want to use a fixed version <version>, replace java/sqreen.jar with java/sqreen-<version>.jar.

Agent in repository

curl https://download.sqreen.io/java/sqreen.jar -o sqreen.jar

Modify Java command line parameters

Add Sqreen Java agent to command line parameters in Procfile.

web: java -javaagent:/app/sqreen.jar -jar your-app-1.0.jar

Set your Sqreen token

Set your Sqreen token (provided from your User Interface) in your application environment variables

heroku config:set SQREEN_TOKEN=<put-your-token-value-here>

From your terminal, in your application root directory: commit your changes and push them to Heroku in order to trigger the deploy of your modifications:

git add .
git commit -m 'Add Sqreen to my application'
git push heroku master

Using Sqreen with PHP

Sqreen supports all available major PHP versions on all the Heroku buildpacks. As of the time of writing, this means PHP 5.6-7.3 in (the deprecated) cedar-14, PHP 5.6-7.4 in the heroku-16 stack and PHP 7.1-7.4 in the heroku-18 stack. The installation involves several steps.

First, you need to add the Sqreen addon to your application. This will automatically define SQREEN_TOKEN environment variable.

Second, you need to add an extra repository to the application. The repository to use varies according to your buildpack:

# cedar-14
heroku config:set HEROKU_PHP_PLATFORM_REPOSITORIES="https://sqreen-heroku.s3.amazonaws.com/dist-cedar-14-stable/"

# heroku-16
heroku config:set HEROKU_PHP_PLATFORM_REPOSITORIES="https://sqreen-heroku.s3.amazonaws.com/dist-heroku-16-stable/"

# heroku-18
heroku config:set HEROKU_PHP_PLATFORM_REPOSITORIES="https://sqreen-heroku.s3.amazonaws.com/dist-heroku-18-stable/"

Finally, you need to edit your composer.json. Add ext-sqreen to the require section and to the config/platform section:

{
   ...
    "require": {
        "php": "^7.1.3",
        "ext-sqreen": "^1.10",
        ...
    },
    ...
    "config": {
        "platform": {
            "php": "7.1.3",
            "ext-sqreen": "1.10.0"
        },
       ...
    },
    ...
}

Then commit and deploy. The installation is complete. You can check the logs to confirm.

In order to upgrade Sqreen, you merely need to redeploy your application. As long as the new version number matches the constraint in the require section of composer.json, it will be picked up.

The Sqreen dashboard

The Sqreen dashboard provides a bird’s-eye view of your application security.

Sqreen is made of extensible plugins ranging from data protection (OWASP Top 10 and more) to user protection (Bruteforce, Account Takeovers and more). Each plugin monitors a critical activity in your application (database access, shell command execution, file inclusion, etc) and enables you to respond and be notified the way you want to.

For more information about plugins, you can visit our Security Hub.

You can access your Sqreen dashboard from the Heroku CLI:

$ heroku addons:open sqreen
Opening sqreen for sharp-mountain-4005

You can also access the Sqreen dashboard by visiting your Heroku Dashboard, pick an app where Sqreen is installed and select it from the Resources > Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade sqreen:newplan
-----> Upgrading sqreen:newplan to sharp-mountain-4005... done, v18 ($X/mo)
       Your plan has been updated to: sqreen:newplan

Removing the add-on

You can remove Sqreen via the CLI:

$ heroku addons:destroy sqreen
-----> Removing sqreen from sharp-mountain-4005... done, v20 (free)

Support

All Sqreen support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at hey@sqreen.io.