Install the Go agent

The Go agent is a Go module that can be installed using regular go commands. The following sections describe how to add the agent to your dependencies and compile your Go program with it.

Refer to the Microagent compatibility matrix for details about the compatability between Sqreen and your Go application.

Quick Start

Quickly start using Sqreen for Go with the following Go HTTP server examples.

Installation Instructions

Set the HTTP middleware function

Use the HTTP middleware function for your web framework:

// Code snippet for net/http
package main
import (
    "github.com/gin-gonic/gin"
    "github.com/sqreen/go-agent/sdk/middleware/sqhttp"
)
func main() {
    mux := http.NewServeMux()
    // ...
    // Wrap your ServeMux with Sqreen's middleware function
    http.ListenAndServe(":http", sqhttp.Middleware(mux))
}

// Code snippet for gin
package main
import (
    "github.com/gin-gonic/gin"
    "github.com/sqreen/go-agent/sdk/middleware/sqgin"
)
func main() {
    router := gin.New()
    router.Use(sqgin.Middleware())
    // ...
}

// Code snippet for echo
package main
import (
    "github.com/labstack/echo/v4"
    "github.com/sqreen/go-agent/sdk/middleware/sqecho/v4"
)
func main() {
    router := echo.New()
    router.Use(sqgin.Middleware())
    // ...
}

// Code snippet for gorilla/mux
package main
import (
    "github.com/gorilla/mux"
    "github.com/sqreen/go-agent/sdk/middleware/sqhttp"
)
func main() {
    router := mux.NewRouter()
    // Wrap your Gorilla Mux with Sqreen's middleware function
    router.Use(sqhttp.Middleware)
    // ...
}

// Code snippet for beego
package main
import (
    "github.com/astaxie/beego"
    "github.com/sqreen/go-agent/sdk/middleware/sqhttp"
)
func main() {
    app := beego.NewApp()
    // ...
    app.Run(sqhttp.Middleware)
}

Compile your program with Sqreen

Sqreen allows you to manage your application protections on your live running applications without recompiling and redeploying them. This is made possible thanks to run-time instrumentation allowing the agent to dynamically attach protections to your running programs. For example, once you enable the SQLi protection module, it can attach the SQL-injection protection to the Go SQL library.

To do so, we leverage compile-time instrumentation in order to add safe run-time instrumentation capabilities to Go.

The following sections walk you through how to install our Go instrumentation tool and compile your Go program using it.

Install the instrumentation tool

Use go get to download, compile and install the instrumentation tool:

$ go get -v github.com/sqreen/go-agent/sdk/sqreen-instrumentation-tool

By default, the resulting sqreen-instrumentation-tool tool is installed in the bin directory of the GOPATH. You can find it using go env GOPATH.

Configure the Go toolchain to use it

Use the instrumentation tool using the go options -a -toolexec /path/to/sqreen-instrumentation-tool.

It can be done either in your Go compilation command lines or by setting the GOFLAGS environment variable.

For example:

$ go build -a -toolexec $(go env GOPATH)/bin/sqreen-instrumentation-tool my-project

$ GOFLAGS="-a -toolexec $(go env GOPATH)/bin/sqreen-instrumentation-tool"
$ go build my-project

# Compiling a Go module with Docker
FROM golang
WORKDIR /app
COPY . .
RUN go build -v github.com/sqreen/go-agent/sdk/sqreen-instrumentation-tool
RUN go build -v -a -toolexec ./sqreen-instrumentation-tool my-project

The same applies to go get and go install.

In case of compilation issues, please refer to the advanced installation section to find details on the compilation requirements.

Compilation errors

Please refer to our troubleshooting page if you experience compilation errors. Common issues such as missing files because of vendoring issues are detailed.

Instrumentation Details

Sqreen is the first security platform to provide Runtime Application Self-Protection (RASP) for Go. You can read more about RASP and why Sqreen for Go requires compile-time instrumentation in this blog post.

Configure the agent

The agent will start when credentials are configured. To do so:

  1. Sign up to Sqreen to create your account.
  2. Add a new host to get your credentials.
  3. Set the configuration by environment variable or file.

For example: 

app_name: "Your Go Service Name"
token: "Your Token"
Find out more about how to set up the configuration here.

List of instrumented packages

The least amount of Go packages are instrumented. The following list gives you the current instrumented packages and the reasons why:

  • github.com/sqreen/go-agent/internal/protection: agent-internal protection package where we hook our basic protections - such as the In-App WAF and Security Headers - used by our middleware functions.

  • database/sql: RASP SQL-injection protection.

  • net/http: RASP Server-Side Request Forgery protection of the HTTP client, and In-App WAF protection of the parsed form values when using ParseForm().

  • os: RASP Local File Inclusion, Shell Injection and Shellshock protections.

  • go.mongodb.org/mongo-driver/mongo: RASP noSQL-injection protection.

  • github.com/gin-gonic/gin: In-App WAF protection of the parsed request parameters (eg. a JSON body value) when using Gin's Bind() methods.

  • github.com/labstack/echo: In-App WAF protection of the parsed request parameters (eg. a JSON body value) when using Echo's Bind() methods.

The list of instrumented packages will evolve as we release new RASP protections.

Feel free to use the verbose instrumentation mode of the instrumentation tool using the -v flag in order to see the full details of what it does. You can also have a look at the instrumented Go source code that is generated into the Go build directory using the Go build option -work.

Advanced installation

Agent compilation requirements

The agent compilation involves CGO and therefore requires:

  • The gcc compiler for the target GOOS and GOARCH.
  • The C library headers.
  • The CGO bindings enabled. This is controlled by the CGO_ENABLED environment variable which is enabled by default when compiling natively.
    If CGO is disabled, major agent features such as RASP and WAF will be disabled.

Examples of requirements installation on common systems:

$ apt install gcc libc6-dev

$ apk add gcc musl-dev

$ yum install gcc glibc-devel

$ xcode-select --install

Cross-compilation

The go toolchain disables CGO when cross-compiling. See the section dedicated to cross-compilation to know more.

Cross-compilation

Cross-compiling with CGO needs the gcc compiler and C headers for the target GOOS and GOARCH.

Here are a few examples from a Debian system which provides pre-compiled cross-compilers that are commonly used:

$ sudo apt install gcc-mingw-w64-x86-64
$ env GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc go build your-go-app

$ sudo apt install gcc-aarch64-linux-gnu
$ env GOOS=linux GOARCH=arm64 CGO_ENABLED=1 CC=aarch64-linux-gnu-gcc go build your-go-app

Please, let us know if your target compiler is not available on your system by creating an issue here.

Advanced integration

The Go Agent SDK allows further integrations in order to enable security automation and user monitoring, including protection from user account takeovers, need explicit usage of the SDK. They are based on a few events that need to be added to your Go apps and documented in the following sections:

Uninstalling the agent

To uninstall the agent, remove the package from your imported packages.

Troubleshooting

Please refer to our troubleshooting page if you experience compilation errors. Common issues such as missing files because of vendoring issues are detailed.