|
| 1 | +/* |
| 2 | + * Copyright (c) 2024. Devtron Inc. |
| 3 | + * |
| 4 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + * you may not use this file except in compliance with the License. |
| 6 | + * You may obtain a copy of the License at |
| 7 | + * |
| 8 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | + * |
| 10 | + * Unless required by applicable law or agreed to in writing, software |
| 11 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + * See the License for the specific language governing permissions and |
| 14 | + * limitations under the License. |
| 15 | + */ |
| 16 | + |
| 17 | +package audit |
| 18 | + |
| 19 | +import ( |
| 20 | + "encoding/json" |
| 21 | + "time" |
| 22 | +) |
| 23 | + |
| 24 | +// TimeFormat is the wire format for AuditLogEvent.Time (ISO-8601, numeric zone). |
| 25 | +const TimeFormat = "2006-01-02T15:04:05-0700" |
| 26 | + |
| 27 | +// RouteName builds the MODULE:RESOURCE:ACTION route name read back by the |
| 28 | +// orchestrator's audit log service. Using this helper keeps route tags |
| 29 | +// consistent with the typed Module/Resource/Action constants instead of |
| 30 | +// hand-written strings. |
| 31 | +func RouteName(module AuditModule, resource AuditResource, action AuditAction) string { |
| 32 | + return string(module) + ":" + string(resource) + ":" + string(action) |
| 33 | +} |
| 34 | + |
| 35 | +// ResourceRef identifies the concrete resource an audited action touched. |
| 36 | +type ResourceRef struct { |
| 37 | + Type string `json:"type"` |
| 38 | + Name string `json:"name,omitempty"` |
| 39 | +} |
| 40 | + |
| 41 | +// EnrichmentEntity carries the raw identifier (e.g. an app_id) that the |
| 42 | +// audit-log service resolves into the full entity during enrichment. |
| 43 | +type EnrichmentEntity struct { |
| 44 | + Identifier string `json:"identifier"` |
| 45 | +} |
| 46 | + |
| 47 | +// AuditLogEvent is the canonical NATS payload published on AUDIT_LOG_TOPIC. |
| 48 | +// It is shared between the publisher (orchestrator) and the consumer |
| 49 | +// (audit-log service) so both agree on the contract. |
| 50 | +type AuditLogEvent struct { |
| 51 | + ApiPath string `json:"apiPath"` |
| 52 | + Time string `json:"time"` |
| 53 | + Resource ResourceRef `json:"resource"` |
| 54 | + Module string `json:"module"` |
| 55 | + Type string `json:"type"` // action verb, e.g. "create" |
| 56 | + Action string `json:"action"` // human sentence, e.g. "Created application 'dashboard'" |
| 57 | + UpdatedBy string `json:"updatedBy"` // acting user (email) who performed the action |
| 58 | + ClientIp string `json:"clientIp"` // client IP the request originated from |
| 59 | + RequestMethod string `json:"requestMethod"` // HTTP method of the audited request |
| 60 | + ApiResponseCode int `json:"apiResponseCode"` // HTTP status code the request returned |
| 61 | + ResponseTime time.Duration `json:"responseTime"` // request handling duration (nanoseconds) |
| 62 | + Payload map[string]interface{} `json:"payload"` // the actual request body of the audited call, always present |
| 63 | + EnrichmentContext map[string]EnrichmentEntity `json:"enrichmentContext,omitempty"` |
| 64 | +} |
| 65 | + |
| 66 | +// NewAuditLogEvent constructs an event with the structural metadata parsed |
| 67 | +// from a route name. eventTime is supplied by the caller (time.Now()) so this |
| 68 | +// package stays free of implicit clock reads. |
| 69 | +func NewAuditLogEvent(apiPath string, eventTime time.Time, module AuditModule, resourceType AuditResource, action AuditAction) *AuditLogEvent { |
| 70 | + return &AuditLogEvent{ |
| 71 | + ApiPath: apiPath, |
| 72 | + Time: eventTime.Format(TimeFormat), |
| 73 | + Module: module.ToString(), |
| 74 | + Type: action.ToString(), |
| 75 | + Resource: ResourceRef{Type: resourceType.ToString()}, |
| 76 | + Payload: make(map[string]interface{}), |
| 77 | + EnrichmentContext: make(map[string]EnrichmentEntity), |
| 78 | + } |
| 79 | +} |
| 80 | + |
| 81 | +// WithResourceName sets the human-facing name of the affected resource. |
| 82 | +func (e *AuditLogEvent) WithResourceName(name string) *AuditLogEvent { |
| 83 | + e.Resource.Name = name |
| 84 | + return e |
| 85 | +} |
| 86 | + |
| 87 | +// WithActor records the acting user (email) and originating client IP. The |
| 88 | +// acting user is always available and is the "updated by" of the audited action. |
| 89 | +func (e *AuditLogEvent) WithActor(updatedBy, clientIp string) *AuditLogEvent { |
| 90 | + e.UpdatedBy = updatedBy |
| 91 | + e.ClientIp = clientIp |
| 92 | + return e |
| 93 | +} |
| 94 | + |
| 95 | +// WithRequest records the request's HTTP method, response status code and |
| 96 | +// handling duration. |
| 97 | +func (e *AuditLogEvent) WithRequest(method string, apiResponseCode int, responseTime time.Duration) *AuditLogEvent { |
| 98 | + e.RequestMethod = method |
| 99 | + e.ApiResponseCode = apiResponseCode |
| 100 | + e.ResponseTime = responseTime |
| 101 | + return e |
| 102 | +} |
| 103 | + |
| 104 | +// IsApiSuccess reports whether the audited request completed successfully (HTTP 2xx). |
| 105 | +// Only successful actions are published to NATS — failed or denied requests |
| 106 | +// (4xx/5xx) are not audited. |
| 107 | +func (e *AuditLogEvent) IsApiSuccess() bool { |
| 108 | + return e.ApiResponseCode >= 200 && e.ApiResponseCode < 300 |
| 109 | +} |
| 110 | + |
| 111 | +// WithAction sets the human-readable action sentence. |
| 112 | +func (e *AuditLogEvent) WithAction(action string) *AuditLogEvent { |
| 113 | + e.Action = action |
| 114 | + return e |
| 115 | +} |
| 116 | + |
| 117 | +// WithPayloadField adds a single key/value to the payload bag. |
| 118 | +func (e *AuditLogEvent) WithPayloadField(key string, value interface{}) *AuditLogEvent { |
| 119 | + if e.Payload == nil { |
| 120 | + e.Payload = make(map[string]interface{}) |
| 121 | + } |
| 122 | + e.Payload[key] = value |
| 123 | + return e |
| 124 | +} |
| 125 | + |
| 126 | +// WithEnrichment records an identifier (e.g. app_id) under an entity key |
| 127 | +// (e.g. "app") for the consumer to resolve. Empty identifiers are ignored so |
| 128 | +// callers can pass through missing path vars without polluting the context. |
| 129 | +func (e *AuditLogEvent) WithEnrichment(entity, identifier string) *AuditLogEvent { |
| 130 | + if identifier == "" { |
| 131 | + return e |
| 132 | + } |
| 133 | + if e.EnrichmentContext == nil { |
| 134 | + e.EnrichmentContext = make(map[string]EnrichmentEntity) |
| 135 | + } |
| 136 | + e.EnrichmentContext[entity] = EnrichmentEntity{Identifier: identifier} |
| 137 | + return e |
| 138 | +} |
| 139 | + |
| 140 | +// Marshal serializes the event to a JSON string for PubSubClientService.Publish. |
| 141 | +func (e *AuditLogEvent) Marshal() (string, error) { |
| 142 | + data, err := json.Marshal(e) |
| 143 | + if err != nil { |
| 144 | + return "", err |
| 145 | + } |
| 146 | + return string(data), nil |
| 147 | +} |
| 148 | + |
| 149 | +// UnmarshalAuditLogEvent parses a NATS payload back into an event (consumer side). |
| 150 | +func UnmarshalAuditLogEvent(data string) (*AuditLogEvent, error) { |
| 151 | + event := &AuditLogEvent{} |
| 152 | + if err := json.Unmarshal([]byte(data), event); err != nil { |
| 153 | + return nil, err |
| 154 | + } |
| 155 | + return event, nil |
| 156 | +} |
0 commit comments