Skip to content

Commit 1d96431

Browse files
MaartendeKruijfMaartendeKruijf
authored
Feature/134 update openapi specification to include examples for models (#160)
1 parent 5f91367 commit 1d96431

File tree

4 files changed

+54
-34
lines changed

4 files changed

+54
-34
lines changed

‎main.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,9 @@ const banner = `
3232
3333
`
3434

35+
// @title SOARCA API
36+
// @version 1.0.0
37+
// @host localhost:8080
3538
func main() {
3639
fmt.Print(banner)
3740
log.Info("Version: ", Version)

‎models/api/error.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
package api
2+
3+
type Error struct {
4+
Status int `json:"status" validate:"required" example:"400"`
5+
Message string `json:"message" validate:"required" example:"missing argument in call"`
6+
OriginalCall string `json:"original-call" validate:"required" example:"/example/route"`
7+
DownstreamCall string `json:"downstream-call" validate:"omitempty" example:"{\"some\" : \"json\"}"`
8+
}

‎models/api/execution.go‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
package api
2+
3+
import "github.com/google/uuid"
4+
5+
type Execution struct {
6+
ExecutionId uuid.UUID `json:"execution_id" validate:"required" example:"2c855cd6-bbce-402f-a143-3d6eec346c08"`
7+
PlaybookId string `json:"payload" validate:"required" example:"playbook--0cec398c-db69-4f17-bde4-8ecbcc4a8879"`
8+
}

‎models/cacao/cacao.go‎

Lines changed: 35 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -55,13 +55,14 @@ type (
5555
Workflow map[string]Step
5656
)
5757

58+
// CACAO Variable
5859
type Variable struct {
59-
Type string `bson:"type" json:"type" validate:"required"`
60-
Name string `bson:"name,omitempty" json:"name,omitempty"`
61-
Description string `bson:"description,omitempty" json:"description,omitempty"`
62-
Value string `bson:"value,omitempty" json:"value,omitempty"`
63-
Constant bool `bson:"constant,omitempty" json:"constant,omitempty"`
64-
External bool `bson:"external,omitempty" json:"external,omitempty"`
60+
Type string `bson:"type" json:"type" validate:"required" example:"string"` // Type of the variable should be OASIS variable-type-ov
61+
Name string `bson:"name,omitempty" json:"name,omitempty" example:"__example_string__"` // The name of the variable in the style __variable_name__
62+
Description string `bson:"description,omitempty" json:"description,omitempty" example:"some string"` // A description of the variable
63+
Value string `bson:"value,omitempty" json:"value,omitempty" example:"this is a value"` // The value of the that the variable will evaluate to
64+
Constant bool `bson:"constant,omitempty" json:"constant,omitempty" example:"false"` // Indicate if it's a constant
65+
External bool `bson:"external,omitempty" json:"external,omitempty" example:"false"` // Indicate if it's external
6566
}
6667

6768
const (
@@ -85,34 +86,34 @@ const (
8586
type Variables map[string]Variable
8687

8788
type Playbook struct {
88-
ID string `bson:"_id" json:"id" validate:"required"`
89-
Type string `bson:"type" json:"type" validate:"required"`
90-
SpecVersion string `bson:"spec_version" json:"spec_version" validate:"required"`
91-
Name string `bson:"name" json:"name" validate:"required"`
92-
Description string `bson:"description,omitempty" json:"description,omitempty"`
93-
PlaybookTypes []string `bson:"playbook_types,omitempty" json:"playbook_types,omitempty"`
94-
CreatedBy string `bson:"created_by" json:"created_by" validate:"required"`
95-
Created time.Time `bson:"created" json:"created" validate:"required"`
96-
Modified time.Time `bson:"modified" json:"modified" validate:"required"`
97-
ValidFrom time.Time `bson:"valid_from,omitempty" json:"valid_from,omitempty"`
98-
ValidUntil time.Time `bson:"valid_until,omitempty" json:"valid_until,omitempty" validate:"omitempty,gtecsfield=ValidFrom"`
99-
DerivedFrom []string `bson:"derived_from,omitempty" json:"derived_from,omitempty"`
100-
Priority int `bson:"priority,omitempty" json:"priority,omitempty"`
101-
Severity int `bson:"severity,omitempty" json:"severity,omitempty"`
102-
Impact int `bson:"impact,omitempty" json:"impact,omitempty"`
103-
Labels []string `bson:"labels,omitempty" json:"labels,omitempty"`
104-
ExternalReferences []ExternalReferences `bson:"external_references,omitempty" json:"external_references,omitempty"`
105-
Markings []string `bson:"markings,omitempty" json:"markings,omitempty"`
106-
WorkflowStart string `bson:"workflow_start" json:"workflow_start" validate:"required"`
107-
WorkflowException string `bson:"workflow_exception,omitempty" json:"workflow_exception,omitempty"`
108-
Workflow Workflow `bson:"workflow" json:"workflow" validate:"required"`
109-
DataMarkingDefinitions map[string]DataMarking `bson:"data_marking_definitions,omitempty" json:"data_marking_definitions,omitempty"`
110-
AuthenticationInfoDefinitions map[string]AuthenticationInformation `bson:"authentication_info_definitions,omitempty" json:"authentication_info_definitions,omitempty"`
111-
AgentDefinitions map[string]AgentTarget `bson:"agent_definitions,omitempty" json:"agent_definitions,omitempty"`
112-
TargetDefinitions map[string]AgentTarget `bson:"target_definitions,omitempty" json:"target_definitions,omitempty"`
113-
ExtensionDefinitions map[string]ExtensionDefinition `bson:"extension_definitions,omitempty" json:"extension_definitions,omitempty"`
114-
PlaybookVariables Variables `bson:"playbook_variables,omitempty" json:"playbook_variables,omitempty"`
115-
PlaybookExtensions Extensions `bson:"playbook_extensions,omitempty" json:"playbook_extensions,omitempty"`
89+
ID string `bson:"_id" json:"id" validate:"required" example:"playbook--77c4c428-6304-4950-93ff-83c5fd4cb67a"` // Used by SOARCA so refer to the object while loading it from the database
90+
Type string `bson:"type" json:"type" validate:"required" example:"playbook"` // Must be playbook
91+
SpecVersion string `bson:"spec_version" json:"spec_version" validate:"required" example:"cacao-2.0"` // Indicate the specification version cacao-2.0 is the only supported version at this time
92+
Name string `bson:"name" json:"name" validate:"required" example:"Investigation playbook"` // An indicative name of the playbook
93+
Description string `bson:"description,omitempty" json:"description,omitempty" example:"This is an example investigation playbook"` // A descriptive text to indicate what your playbook does
94+
PlaybookTypes []string `bson:"playbook_types,omitempty" json:"playbook_types,omitempty" example:"investigation"` // Should be of the CACAO playbook-type-ov
95+
CreatedBy string `bson:"created_by" json:"created_by" validate:"required" example:"identity--96abab60-238a-44ff-8962-5806aa60cbce"` // UUID referring to identity
96+
Created time.Time `bson:"created" json:"created" validate:"required" example:"2024-01-01T09:00:00.000Z"` // Timestamp of the creation of the playbook
97+
Modified time.Time `bson:"modified" json:"modified" validate:"required" example:"2024-01-01T09:00:00.000Z"` // Timestamp of the last modification of the playbook
98+
ValidFrom time.Time `bson:"valid_from,omitempty" json:"valid_from,omitempty" example:"2024-01-01T09:00:00.000Z"` // Timestamp from when the playbook is valid
99+
ValidUntil time.Time `bson:"valid_until,omitempty" json:"valid_until,omitempty" validate:"omitempty,gtecsfield=ValidFrom" example:"2124-01-01T09:00:00.000Z"` // Timestamp until when the playbook is valid
100+
DerivedFrom []string `bson:"derived_from,omitempty" json:"derived_from,omitempty" example:"[\"playbook--77c4c428-6304-4950-93ff-83c5224cb67a\"]"` // Playbook id that this playbook is derived from
101+
Priority int `bson:"priority,omitempty" json:"priority,omitempty" example:"100"` // A priority number ranging 0 - 100
102+
Severity int `bson:"severity,omitempty" json:"severity,omitempty" example:"100"` // A priority number ranging 0 - 100
103+
Impact int `bson:"impact,omitempty" json:"impact,omitempty" example:"100"` // A priority number ranging 0 - 100
104+
Labels []string `bson:"labels,omitempty" json:"labels,omitempty"` // List of labels to label playbook
105+
ExternalReferences []ExternalReferences `bson:"external_references,omitempty" json:"external_references,omitempty"` // List of external reference objects
106+
Markings []string `bson:"markings,omitempty" json:"markings,omitempty" example:"[marking-statement--6424867b-0440-4885-bd0b-604d51786d06]"` // List of datamarking identifiers
107+
WorkflowStart string `bson:"workflow_start" json:"workflow_start" validate:"required" example:"start--07bea005-4a36-4a77-bd1f-79a6e4682a13"` // Start step of the playbook MUST be of step type START
108+
WorkflowException string `bson:"workflow_exception,omitempty" json:"workflow_exception,omitempty" example:"end--37bea005-4a36-4a77-bd1f-79a6e4682a13"` // Step that marks the actions that need to be taken when an exception occurs
109+
Workflow Workflow `bson:"workflow" json:"workflow" validate:"required"` // Map of workflow steps keyed by the step id
110+
DataMarkingDefinitions map[string]DataMarking `bson:"data_marking_definitions,omitempty" json:"data_marking_definitions,omitempty"` // Map of datamarking definitions
111+
AuthenticationInfoDefinitions map[string]AuthenticationInformation `bson:"authentication_info_definitions,omitempty" json:"authentication_info_definitions,omitempty"` // Map of authentication information objects
112+
AgentDefinitions map[string]AgentTarget `bson:"agent_definitions,omitempty" json:"agent_definitions,omitempty"` // Map of agent definitions used by the workflow steps
113+
TargetDefinitions map[string]AgentTarget `bson:"target_definitions,omitempty" json:"target_definitions,omitempty"` // Map of target definitions used by the workflow steps
114+
ExtensionDefinitions map[string]ExtensionDefinition `bson:"extension_definitions,omitempty" json:"extension_definitions,omitempty"` // Map of extension definitions used by the workflow steps
115+
PlaybookVariables Variables `bson:"playbook_variables,omitempty" json:"playbook_variables,omitempty"` // Map of variables that are global to the playbook
116+
PlaybookExtensions Extensions `bson:"playbook_extensions,omitempty" json:"playbook_extensions,omitempty"` // Map of extensions used by the playbook
116117
}
117118

118119
type CivicLocation struct {

0 commit comments

Comments
 (0)