Adding proper documentation

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/).
+<!-- omit in toc -->
+# 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:       "<your_api_key>",
-		URL:         "<your_intelowl_instance_url>",
-		Certificate: "optional<path_to_pem_file>",
+
+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)
+	}
 }
+
 ```
+<!-- TODO: ADD THE PKG LINK-->
+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.

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 ==========")
+	}
+}

examples/basicExample/example.md

@@ -0,0 +1,2 @@
+# Example
+This example will show you how to do a basic scan!

examples/client/client.md

@@ -0,0 +1,11 @@
+<!-- Will be revised when I'll add the custom logger and easy ways of setting the client up! -->
+# 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. 

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))
+		}
+	}
+
+}

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))
+		}
+	}
+
+}

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)