[rewrite] Break up into service objects/resources

[eshaan7]

I don't like approach of just appending functions to the IntelOwlClient struct.

This SDK should be created following the approach given in this blog-post, especially the "Service Objects" heading.

This approach is very similar to how we (at Certego) wrote pydragonfly recently using the django-rest-client framework (also written by us).

[uzaxirr]

Adding more useful articles for reference

• Go client library best practices

[0x0elliot]

Hey, I would like to take over this issue! If there are any other relevant resources and projects out there that meet your expectations from where you would like me to take inspiration from written specifically in GOLang, please link them here as well! I am a bit new to GOLang but I would like to learn further for this project.

[0x0elliot]

I also feel like the error handling here isn't done very well at the moment. For example, here, log.Fatalln(err) would just exit the program. It seems better to handle the errors more gracefully for a library. Maybe we can look into wrapping the errors in the functions/methods as well?

[eshaan7]

^Yes, that's the point of the rewrite. The current code (the methods inside the IntelOwlClient struct) are to be completely discarded.

[0x0elliot]

I am in the process of finishing this. Just a heads up!

[0x0elliot]

Kindly review my PR and let me know how I can make it better!

[eshaan7]

Defining some basic primitives of what we are looking for.

1. Since we want to use the "Service Objects" pattern, the ideal naming convention would be something like this:

c := IntelOwlClient(opts* IntelOwlClientOptions)
c.Job.List() -> []Job // will not take params because we will hard-code `?paginate=false` URL parameter.
c.Job.Get(id uint64) -> Job
c.Job.Delete(id uint64) -> bool
c.Job.DownloadSample(id uint64) -> []byte // or FileReader object?
c.Job.Kill(id uint64) -> bool
c.Job.Retry(id uint64) -> bool
c.Job.KillAnalyzer(id uint64, analyzerName string) -> bool
c.Job.KillConnector(id uint64, connectorName string) -> bool
c.Job.RetryAnalyzer(id uint64, analyzerName string) -> bool
c.Job.RetryConnector(id uint64, connectorName string) -> bool
c.Tag.List() -> []Tag // does not require URL params
c.Tag.Get(id uint64) -> Tag
c.Tag.Create(params* TagParams) -> Tag
c.Tag.Update(id uint64, params* TagParams) -> Tag
c.Tag.Delete(id uint64) -> bool
c.CreateFileAnalysis(params* FileAnalysisParams) -> AnalysisResponse
c.CreateObservableAnalysis(params* ObservableAnalysisParams) -> AnalysisResponse
c.Analyzer.GetConfigs() -> []AnalyzerConfig
c.Analyzer.HealthCheck(analyzerName string) -> bool
c.Connector.GetConfigs() -> []ConnectorConfig
c.Connector.HealthCheck(connectorName string) -> bool

2. We want to provide struct definitions for all request parameters and in some cases also the response parameters. For example:

// basic
type IntelOwlClientOptions struct {} // will contain url, token, certificate, etc.
// response
type Tag struct {
    ID uint64 `json:"id"`
    Label string `json:"label"`
    Color  string `json:"color"`
}
type Job struct {} // see JobSerializer on IntelOwl:dev-v4
type AnalysisResponse struct {} // see AnalysisResponseSerializer on IntelOwl:dev-v4
type AnalyzerConfig struct {}
type ConnectorConfig struct {}
// request
type TagParams struct {}
type FileAnalysisParams struct {} //  see FileAnalysisSerializer on IntelOwl:dev-v4
type ObservableAnalysisParams struct {}  // see ObservableAnalysisSerializer on IntelOwl:dev-v4

You can also refer to the pyintelowl.py for request parameters specification.

[fear-the-reaper]

API Endpoints TODO list:

Tick when merged with master/main

Tags

• GET /api/tags
• GET /api/tags/{id}
• POST /api/tags/
• PUT /api/tags/{id}
• DELETE /api/tags/{id}

Analyzer

• GET /api/get_analyzer_configs
• GET /api/analyzer/{NameOfAnalyzer}/healthcheck

Connector

• GET /api/get_connector_configs
• GET /api/connector/{NameOfConnector/healthcheck

Job

• GET /api/jobs
• GET /api/jobs/{id}
• DELETE /api/jobs/{id}
• GET /api/jobs/{id}/download_sample
• PATCH /api/jobs/{id}/kill
• PATCH /api/jobs/{id}/analyzer/{nameOfAnalyzer}/kill
• PATCH /api/jobs/{id}/analyzer/{nameOfAnalyzer}/retry
• PATCH /api/jobs/{id}/connector/{nameOfConnector}/kill
• PATCH /api/jobs/{job_id}/connector/{name}/retry

Analysis

• POST /api/analyze_observable
• POST /api/analyze_multiple_observables
• POST /api/analyze_file
• POST /api/analyze_multiple_files

Me (User details)

• GET /api/me/access
• GET /api/me/organization
• POST /api/me/organization
• POST /api/me/organization/invite
• POST /api/me/organization/remove_member

Playbooks

• GET /api/get_playbooks_config
• POST /api/playbook/analyse_observable
• POST /api/playbook/analyse_file

[sp35]

Closing this as completed, #60 has been opened for playbook endpoints.