-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
113 changed files
with
16,973 additions
and
72 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,165 @@ | ||
:fontawesome-brands-github: [Go-IntelOwl Repository](https://github.com/intelowlproject/go-intelowl) | ||
|
||
# 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) | ||
|
||
![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! | ||
|
||
<!-- 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) | ||
- [License](#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 | ||
``` | ||
|
||
## 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 go-intelowl 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 | ||
|
||
import ( | ||
"fmt" | ||
|
||
"github.com/intelowlproject/go-intelowl/gointelowl" | ||
) | ||
|
||
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](https://pkg.go.dev/github.com/intelowlproject/go-intelowl). | ||
|
||
# Contribute | ||
|
||
If you want to follow the updates, discuss, contribute, or just chat then please join our [slack](https://honeynetpublic.slack.com/archives/C01KVGMAKL6) channel we'd love to hear your feedback! | ||
|
||
# License | ||
|
||
Licensed under the GNU AFFERO GENERAL PUBLIC LICENSE. | ||
|
||
# Links | ||
|
||
- [Intelowl](https://github.com/intelowlproject/IntelOwl) | ||
- [Documentation](https://intelowl.readthedocs.io/en/latest/) | ||
- [API documentation](https://intelowl.readthedocs.io/en/latest/Redoc.html) | ||
- [Examples](./examples/) | ||
|
||
# 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. |
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,173 @@ | ||
# Contribute | ||
|
||
## General Guidance | ||
|
||
Please refer to [IntelOwl Documentation](https://intelowl.readthedocs.io/en/latest/) for everything missing here. | ||
|
||
## Rules | ||
|
||
GreedyBear welcomes contributors from anywhere and from any kind of education or skill level. We strive to create a community of developers that is welcoming, friendly and right. | ||
|
||
For this reason it is important to follow some easy rules based on a simple but important concept: **Respect**. | ||
|
||
- Before starting to work on an issue, you need to get the approval of one of the maintainers. Therefore please ask to be assigned to an issue. If you do not that but you still raise a PR for that issue, your PR can be rejected. This is a form of respect for both the maintainers and the other contributors who could have already started to work on the same problem. | ||
|
||
- When you ask to be assigned to an issue, it means that you are ready to work on it. When you get assigned, take the lock and then you disappear, you are not respecting the maintainers and the other contributors who could be able to work on that. So, after having been assigned, you have a week of time to deliver your first _draft_ PR. After that time has passed without any notice, you will be unassigned. | ||
|
||
- Before asking questions regarding how the project works, please read _through all the documentation_ and [install](https://greedybear.readthedocs.io/en/latest/Installation.html) the project on your own local machine to try it and understand how it basically works. This is a form of respect to the maintainers. | ||
|
||
- Once you started working on an issue and you have some work to share and discuss with us, please raise a draft PR early with incomplete changes. This way you can continue working on the same and we can track your progress and actively review and help. This is a form of respect to you and to the maintainers. | ||
|
||
- When creating a PR, please read through the sections that you will find in the PR template and compile it appropriately. If you do not, your PR can be rejected. This is a form of respect to the maintainers. | ||
|
||
## Code Style | ||
|
||
Keeping to a consistent code style throughout the project makes it easier to contribute and collaborate. We make use of [`psf/black`](https://github.com/psf/black) and [isort](https://pycqa.github.io/isort/) for code formatting and [`flake8`](https://flake8.pycqa.org) for style guides. | ||
|
||
## How to start (Setup project and development instance) | ||
|
||
To start with the development setup, make sure you go through all the steps in [Installation Guide](https://greedybear.readthedocs.io/en/latest/Installation.html) and properly installed it. | ||
|
||
Please create a new branch based on the **develop** branch that contains the most recent changes. This is mandatory. | ||
|
||
`git checkout -b myfeature develop` | ||
|
||
Then we strongly suggest to configure [pre-commit](https://github.com/pre-commit/pre-commit) to force linters on every commits you perform: | ||
|
||
```bash | ||
# create virtualenv to host pre-commit installation | ||
python3 -m venv venv | ||
source venv/bin/activate | ||
# from the project base directory | ||
pip install pre-commit | ||
pre-commit install -c .github/.pre-commit-config.yaml | ||
``` | ||
|
||
Remember that whenever you make changes, you need to rebuild the docker image to see the reflected changes. | ||
|
||
#### NOTE about documentation: | ||
|
||
If you made any changes to an existing model/serializer/view, please run the following command to generate a new version of the API schema and docs: | ||
|
||
```bash | ||
docker exec -it greedybear_uwsgi python manage.py spectacular --file docs/source/schema.yml && make html | ||
``` | ||
|
||
### Frontend | ||
|
||
To start the frontend in "develop" mode, you can execute the startup npm script within the folder `frontend`: | ||
|
||
```bash | ||
cd frontend/ | ||
# Install | ||
npm i | ||
# Start | ||
DANGEROUSLY_DISABLE_HOST_CHECK=true npm start | ||
# See https://create-react-app.dev/docs/proxying-api-requests-in-development/#invalid-host-header-errors-after-configuring-proxy for why we use that flag in development mode | ||
``` | ||
|
||
Most of the time you would need to test the changes you made together with the backend. In that case, you would need to run the backend locally too: | ||
|
||
```commandline | ||
docker-compose up | ||
``` | ||
|
||
#### Certego-UI | ||
|
||
The GreedyBear Frontend is tightly linked to the [`certego-ui`](https://github.com/certego/certego-ui) library. Most of the React components are imported from there. Because of this, it may happen that, during development, you would need to work on that library too. | ||
To install the `certego-ui` library, please take a look to [npm link](https://docs.npmjs.com/cli/v8/commands/npm-link) and remember to start certego-ui without installing peer dependencies (to avoid conflicts with GreedyBear dependencies): | ||
|
||
```bash | ||
git clone https://github.com/certego/certego-ui.git | ||
# change directory to the folder where you have the cloned the library | ||
cd certego-ui/ | ||
# install, without peer deps (to use packages of GreedyBear) | ||
npm i --legacy-peer-deps | ||
# create link to the project (this will globally install this package) | ||
sudo npm link | ||
# compile the library | ||
npm start | ||
``` | ||
|
||
Then, open another command line tab, create a link in the `frontend` to the `certego-ui` and re-install and re-start the frontend application (see previous section): | ||
|
||
```bash | ||
cd frontend/ | ||
npm link @certego/certego-ui | ||
``` | ||
|
||
This trick will allow you to see reflected every changes you make in the `certego-ui` directly in the running `frontend` application. | ||
|
||
##### Example application | ||
|
||
The `certego-ui` application comes with an example project that showcases the components that you can re-use and import to other projects, like GreedyBear: | ||
|
||
```bash | ||
# To have the Example application working correctly, be sure to have installed `certego-ui` *without* the `--legacy-peer-deps` option and having it started in another command line | ||
cd certego-ui/ | ||
npm i | ||
npm start | ||
# go to another tab | ||
cd certego-ui/example/ | ||
npm i | ||
npm start | ||
``` | ||
|
||
## Create a pull request | ||
|
||
### Remember!!! | ||
|
||
Please create pull requests only for the branch **develop**. That code will be pushed to master only on a new release. | ||
|
||
Also remember to pull the most recent changes available in the **develop** branch before submitting your PR. If your PR has merge conflicts caused by this behavior, it won't be accepted. | ||
|
||
### Tests | ||
|
||
#### Backend | ||
|
||
##### Install testing requirements | ||
|
||
You have to install `pre-commit` to have your code adjusted and fixed with the available linters: | ||
|
||
```commandline | ||
pip install pre-commit | ||
pre-commit install -c .github/.pre-commit-config.yaml | ||
``` | ||
|
||
Once done that, you won't have to think about linters anymore. | ||
|
||
##### Run all tests | ||
|
||
```commandline | ||
docker exec greedybear_uwsgi python3 manage.py test | ||
``` | ||
|
||
#### Frontend | ||
|
||
All the frontend tests must be run from the folder `frontend`. | ||
The tests can contain log messages, you can suppress then with the environment variable `SUPPRESS_JEST_LOG=True`. | ||
|
||
##### Run all tests | ||
|
||
``` | ||
npm test | ||
``` | ||
|
||
##### Run a specific component tests | ||
|
||
``` | ||
npm test -- -t <componentPath> | ||
// example | ||
npm test tests/components/auth/Login.test.jsx | ||
``` | ||
|
||
##### Run a specific test | ||
|
||
``` | ||
npm test -- -t '<describeString> <testString>' | ||
// example | ||
npm test -- -t "Login component User login" | ||
``` | ||
|
||
if you get any errors, fix them. | ||
Once you make sure that everything is working fine, please squash all of our commits into a single one and finally create a pull request. |
Oops, something went wrong.