diff --git a/Banner.png b/Banner.png new file mode 100644 index 0000000..ca406d3 Binary files /dev/null and b/Banner.png differ diff --git a/README.md b/README.md index d8c286c..d9ef361 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,143 @@ -> ⚠️ This repository is incomplete and not ready to be used. +# go-intelowl +[![GitHub issues](https://img.shields.io/github/issues/intelowlproject/go-intelowl?style=plastic)](https://github.com/intelowlproject/go-intelowl/issues) +[![GitHub license](https://img.shields.io/github/license/intelowlproject/go-intelowl?style=plastic)](https://github.com/intelowlproject/go-intelowl/blob/main/LICENSE) -# GoIntelOwl +![go-banner](./Banner.png) +go-intelowl is a client library/SDK that allows developers to easily automate and integrate [IntelOwl](https://github.com/intelowlproject/IntelOwl) with their own set of tools! -IntelOwl client library/SDK written in [Go](https://golang.org/). + +# Table of Contents +- [go-intelowl](#go-intelowl) +- [Getting Started](#getting-started) + - [Pre requisites](#pre-requisites) + - [Installation](#installation) + - [Usage](#usage) + - [Examples](#examples) +- [Contribute](#contribute) +- [Liscence](#liscence) +- [Links](#links) +- [FAQ](#faq) + - [Generate API key](#generate-api-key) + - [v4.0 and above](#v40-and-above) + - [v4.0 below](#v40-below) + +# Getting Started + +## Pre requisites +- Go 1.17+ + ## Installation +Use go get to retrieve the SDK to add it to your GOPATH workspace, or project's Go module dependencies. ```bash $ go get github.com/intelowlproject/go-intelowl ``` -## Using as a library / SDK +## Usage +This library was built with ease of use in mind! Here are some quick examples to get you started. If you need more example you can go to the [examples directory](./examples/) + +To start using the gointelowl library you first need to import it: +``` +import "github.com/intelowlproject/go-intelowl/gointelowl" +``` +Construct a new `IntelOwlClient`, then use the various services to easily access different parts of Intelowl's REST API. Here's an example of getting all jobs: + +```Go +clientOptions := gointelowl.IntelOwlClientOptions{ + Url: "your-cool-URL-goes-here", + Token: "your-super-secret-token-goes-here", + // This is optional + Certificate: "your-optional-certificate-goes-here", +} + +intelowl := gointelowl.NewIntelOwlClient( + &clientOptions, + nil +) + +ctx := context.Background() + +// returns *[]Jobs or an IntelOwlError! +jobs, err := intelowl.JobService.List(ctx) +``` +For easy configuration and set up we opted for `options` structs. Where we can customize the client API or service endpoint to our liking! For more information go [here](). Here's a quick example! + +```Go +// ...Making the client and context! + +tagOptions = gointelowl.TagParams{ + Label: "NEW TAG", + Color: "#ffb703", +} + +createdTag, err := intelowl.TagService.Create(ctx, tagOptions) +if err != nil { + fmt.Println(err) +} else { + fmt.Println(createdTag) +} +``` +## Examples +The [examples](./examples/) directory contains a couple for clear examples, of which one is partially listed here as well: + +```Go +package main -```go import ( - "github.com/intelowlproject/go-intelowl" + "fmt" + + "github.com/intelowlproject/go-intelowl/gointelowl" ) -client := gointelowl.IntelOwlClient{ - Token: "", - URL: "", - Certificate: "optional", + +func main(){ + intelowlOptions := gointelowl.IntelOwlClientOptions{ + Url: "your-cool-url-goes-here", + Token: "your-super-secret-token-goes-here", + } + Certificate: "your-optional-certificate-goes-here", + + client := gointelowl.NewIntelOwlClient( + &intelowlOptions, + nil, + ) + + ctx := context.Background() + + // Get User details! + user, err := client.UserService.Access(ctx) + if err != nil { + fmt.Println("err") + fmt.Println(err) + } else { + fmt.Println("USER Details") + fmt.Println(*user) + } } + ``` + +For complete usage of go-intelowl, see the full [package docs](). -## FAQ +# Contribute +See our [contributor page]() for details how to contribute. If you want to follow the updates, discuss, or just chat then please join our [slack](https://honeynetpublic.slack.com/archives/C01KVGMAKL6) channel we'd love to hear your feedback! -#### Generate API key -You need a valid API key to interact with the IntelOwl server. -Keys should be created from the admin interface of [IntelOwl](https://github.com/intelowlproject/intelowl): you have to go in the *Durin* section (click on `Auth tokens`) and generate a key there. +# Liscence +Licensed under the GNU AFFERO GENERAL PUBLIC LICENSE. -## Checklist +# Links +- [Intelowl](https://github.com/intelowlproject/IntelOwl) +- [Documentation]() -- [ ] `/api/jobs` -- [ ] `/api/tags` -- [ ] send analysis request APIs -- [ ] `/api/ask_analysis_availability` -- [ ] Job actions like: `download_sample`, `kill`, `retry` -- [ ] `/api/get_analyzer_configs` -- [ ] `/api/get_connector_configs` +# FAQ +## Generate API key +You need a valid API key to interact with the IntelOwl server. +### v4.0 and above +You can get an API by doing the following: +1. Log / Signin into intelowl +2. At the upper right click on your profile from the drop down select `API Access/ Sessions` +3. Then generate an API key or see it! +### v4.0 below +Keys should be created from the admin interface of [IntelOwl](https://github.com/intelowlproject/intelowl): you have to go in the *Durin* section (click on `Auth tokens`) and generate a key there. \ No newline at end of file diff --git a/examples/basicExample/example.go b/examples/basicExample/example.go new file mode 100644 index 0000000..c80818c --- /dev/null +++ b/examples/basicExample/example.go @@ -0,0 +1,56 @@ +package main + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/intelowlproject/go-intelowl/gointelowl" +) + +func main() { + + // Configuring the IntelOwlClient! + clientOptions := gointelowl.IntelOwlClientOptions{ + Url: "PUT-YOUR-INTELOWL-INSTANCE-URL-HERE", + Token: "PUT-YOUR-TOKEN-HERE", + Certificate: "", + } + + // Making the client! + client := gointelowl.NewIntelOwlClient( + &clientOptions, + nil, + ) + + ctx := context.Background() + + basicAnalysisParams := gointelowl.BasicAnalysisParams{ + User: 1, + Tlp: gointelowl.WHITE, + RuntimeConfiguration: map[string]interface{}{}, + AnalyzersRequested: []string{}, + ConnectorsRequested: []string{}, + TagsLabels: []string{}, + } + + observableAnalysisParams := gointelowl.ObservableAnalysisParams{ + BasicAnalysisParams: basicAnalysisParams, + ObservableName: "192.168.69.42", + ObservableClassification: "ip", + } + + analyzerResponse, err := client.CreateObservableAnalysis(ctx, &observableAnalysisParams) + if err != nil { + fmt.Println("err") + fmt.Println(err) + } else { + analyzerResponseJSON, _ := json.Marshal(analyzerResponse) + fmt.Println("JOB ID") + fmt.Println(analyzerResponse.JobID) + fmt.Println("JOB ID END") + fmt.Println("========== ANALYZER RESPONSE ==========") + fmt.Println(string(analyzerResponseJSON)) + fmt.Println("========== ANALYZER RESPONSE END ==========") + } +} diff --git a/examples/basicExample/example.md b/examples/basicExample/example.md new file mode 100644 index 0000000..dc8d1b9 --- /dev/null +++ b/examples/basicExample/example.md @@ -0,0 +1,2 @@ +# Example +This example will show you how to do a basic scan! \ No newline at end of file diff --git a/examples/client/client.md b/examples/client/client.md new file mode 100644 index 0000000..80ea4df --- /dev/null +++ b/examples/client/client.md @@ -0,0 +1,11 @@ + +# Client +A good client is a client that is easy to use, configurable and customizable to a user’s liking. Hence, the client has 2 great features: +1. Configurable HTTP client +2. Customizable timeouts + +## Configurable HTTP client +Now from the documentation, you can see you can pass your `http.Client`. This is to facilitate each user’s requirement and taste! If you don’t pass one (`nil`) a default `http.Client` will be made for you! + +## Customizable timeouts +From `IntelOwlClientOptions` you can add your own timeout to your requests as well. diff --git a/examples/endpoints/endpoints.go b/examples/endpoints/endpoints.go new file mode 100644 index 0000000..3c06289 --- /dev/null +++ b/examples/endpoints/endpoints.go @@ -0,0 +1,69 @@ +package main + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/intelowlproject/go-intelowl/gointelowl" +) + +func main() { + + // Configuring the IntelOwlClient! + clientOptions := gointelowl.IntelOwlClientOptions{ + Url: "PUT-YOUR-INTELOWL-INSTANCE-URL-HERE", + Token: "PUT-YOUR-TOKEN-HERE", + Certificate: "", + } + + // Making the client! + client := gointelowl.NewIntelOwlClient( + &clientOptions, + nil, + ) + + ctx := context.Background() + + /* + Now we can use the client to commnicate with your intelowl instance via the service objects! + For this example I want to Display my tags list and create a new tag! + */ + + fmt.Println("Getting the tag list!") + + // Getting the tag list! + tagList, err := client.TagService.List(ctx) + // checking for any pesky errors if there's any error it'll return an IntelOwlError + if err != nil { + fmt.Println(err) + } else { + // Iterating through the list unless its empty in that case create some using TagService.Create()! + for _, tag := range *tagList { + tagJson, err := json.Marshal(tag) + if err != nil { + fmt.Println(err) + } else { + fmt.Println(string(tagJson)) + } + } + } + + // making the tag parameters! + tagParams := gointelowl.TagParams{ + Label: "your super duper cool tag label!", + Color: "#ffb703", + } + createdTag, err := client.TagService.Create(ctx, &tagParams) + if err != nil { + fmt.Println(err) + } else { + tagJson, err := json.Marshal(createdTag) + if err != nil { + fmt.Println(err) + } else { + fmt.Println(string(tagJson)) + } + } + +} diff --git a/examples/endpoints/endpoints.md b/examples/endpoints/endpoints.md new file mode 100644 index 0000000..e69de29 diff --git a/examples/optionalParams/optionalParams.go b/examples/optionalParams/optionalParams.go new file mode 100644 index 0000000..6964f02 --- /dev/null +++ b/examples/optionalParams/optionalParams.go @@ -0,0 +1,47 @@ +package main + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/intelowlproject/go-intelowl/gointelowl" +) + +/* +For this example I'll be using the tag params! +*/ +func main() { + // Configuring the IntelOwlClient! + clientOptions := gointelowl.IntelOwlClientOptions{ + Url: "PUT-YOUR-INTELOWL-INSTANCE-URL-HERE", + Token: "PUT-YOUR-TOKEN-HERE", + Certificate: "", + } + + // Making the client! + client := gointelowl.NewIntelOwlClient( + &clientOptions, + nil, + ) + + ctx := context.Background() + + // making the tag parameters! + tagParams := gointelowl.TagParams{ + Label: "your super duper cool tag label!", + Color: "#ffb703", + } + createdTag, err := client.TagService.Create(ctx, &tagParams) + if err != nil { + fmt.Println(err) + } else { + tagJson, err := json.Marshal(createdTag) + if err != nil { + fmt.Println(err) + } else { + fmt.Println(string(tagJson)) + } + } + +} diff --git a/examples/optionalParams/optionalParams.md b/examples/optionalParams/optionalParams.md new file mode 100644 index 0000000..599c834 --- /dev/null +++ b/examples/optionalParams/optionalParams.md @@ -0,0 +1,6 @@ +# Optional Parameters +For the sake of simplicity, we decided that for some endpoints we’ll be passing `Option Parameters` this is to facilitate easy access, configuration and automation so that you don’t need to pass in many parameters but just a simple struct that can be easily converted to and from JSON! + +For example, let us look at the `TagParams` we use it as an argument for a method `Create` for `TagService`. From a glance, the `TagParams` look simple. They hold 2 fields: `Label`, and `Color` which can be passed seperatly to the method but imagine if you have many fields! (if you don’t believe see the [`ObservableAnalysisParams`](../../gointelowl/analysis.go)) + +For a practical implementation you can see the [example](./optionalParams.go) \ No newline at end of file