This repository contains the SDK for creating a Receptor that integrates with the Trustero Service.
ReceptorSDK documentation is available on pkg.go.dev. Users are advised to consult this ReceptorSDK documentation together with the comprehensive Receptor Developer Guide and protobuf definitions. To obtain a copy of the guide, please reach out to Trustero Support. The easiest way to learn about the SDK is to consult the set of examples built on top of the SDK. What follows is a subset of these examples that can be found useful as stand-alone programs.
| Example | Description |
|---|---|
| GitLab Receptor | A Receptor that posts GitLab users as evidence |
ReceptorSDK is an open source Trustero project and contributions are welcome.
ReceptorSDK is periodically refreshed to reflect the newest additions to the Trustero API. Users of the SDK are advised to track the latest releases rather closely to ensure proper function in the unlikely event of an incompatible change to a Trustero API.
The developer needs to implement the Receptor interface in their project to create a Receptor.
package main
import (
"github.com/trustero/api/go/receptor_sdk"
"github.com/trustero/api/go/receptor_sdk/cmd"
"github.com/trustero/api/go/receptor_v1"
)
const (
receptorName = "trr-custom"
serviceName = "Custom Service"
)
type Receptor struct {
// YOUR CODE HERE
}
func (r *Receptor) GetReceptorType() string {
return receptorName
}
func (r *Receptor) GetKnownServices() []string {
return []string{serviceName}
}
func (r *Receptor) GetCredentialObj() (credentialObj interface{}) {
return r
}
func (r *Receptor) GetInstructions() (string, error) {
return
}
func (r *Receptor) GetLogo() (string, error) {
return
}
func (r *Receptor) GetConfigObj(credentials interface{}) (err error) {
// YOUR CODE HERE
return
}
func (r *Receptor) GetEvidenceInfo(credentials interface{}) (evidences []*receptor_sdk.Evidence) {
// YOUR CODE HERE
}
func (r *Receptor) Configure(credentials interface{}) (config *receptor_v1.ReceptorConfiguration, err error) {
// YOUR CODE HERE
}
func (r *Receptor) Verify(credentials interface{}) (ok bool, err error) {
// YOUR CODE HERE
return
}
func (r *Receptor) Discover(credentials interface{}) (svcs []*receptor_v1.ServiceEntity, err error) {
// YOUR CODE HERE
return
}
func (r *Receptor) Report(credentials interface{}) (evidences []*receptor_sdk.Evidence, err error) {
// YOUR CODE HERE
return
}
func (r *Receptor) ReportBatch(credentials interface{}, evidenceChan chan []*receptor_sdk.Evidence) {
defer func() {
close(evidenceChan)
}()
// YOUR CODE HERE
return
}
func main() {
cmd.Execute(&Receptor{})
}A real-life example can be found in the examples directory.
A developer does not need to initialize a client to interact with the Trustero service.
All communication to the Trustero service is handled by the ReceptorSDK internally.
If a client needs to be generated for debugging or other use cases, it may be done like this:
rc = client.ServerConn.GetReceptorClient()
if receptorInfo, err = getReceptorConfig(rc); err != nil {
log.Error().Err(err)
}
credentialString = receptorInfo.GetCredential()
fmt.Print(credentialString)
You should be able to run your receptor code via the command line to confirm the Verify and Scan functions produce the correct output.
You can run the Receptor code with the dryrun flag and it will print the output to the console.
You can compile the Receptor code into a binary or run the main file directly.
If you run the main file directly, your command should look something like this:
go run main.go scan dryrun --find-evidence --credentials <base64 encoded string of credential object>
This command will run the Verify, Discover, and Report functions that you wrote and print their output to the console. You should be able to see the final Evidences that are generated by the receptor.