feat(oaslint): add oaslint

api/api/v1/apicategory_types.go

@@ -13,6 +13,41 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// LintingMode controls how linting failures affect API creation.
+type LintingMode string
+
+const (
+	// LintingModeBlock prevents Api creation when linting fails.
+	LintingModeBlock LintingMode = "Block"
+	// LintingModeWarn allows Api creation but surfaces linting issues in status.
+	LintingModeWarn LintingMode = "Warn"
+	// LintingModeNone indicates that no linting is configured for this category.
+	LintingModeNone LintingMode = "None"
+)
+
+// LintingConfig configures OAS specification linting for APIs in this category.
+type LintingConfig struct {
+	// Ruleset is the name of the linter ruleset to apply.
+	// If set, it is passed as a URL-encoded query parameter to the linter API.
+	// +required
+	Ruleset string `json:"ruleset"`
+
+	// Mode controls how linting failures affect API creation.
+	// "Block" (default) prevents Api creation on failure; "Warn" allows it but surfaces issues.
+	// +kubebuilder:validation:Enum=Block;Warn;None
+	// +kubebuilder:default:=Block
+	// +optional
+	Mode LintingMode `json:"mode,omitempty"`
+
+	// WhitelistedBasepaths is a list of API basepaths that are exempt from linting.
+	// APIs whose basePath matches an entry here will skip linting even when linting is configured.
+	// Each entry must start with a leading slash.
+	// +optional
+	// +listType=set
+	// +kubebuilder:validation:items:Pattern=`^/`
+	WhitelistedBasepaths []string `json:"whitelistedBasepaths,omitempty"`
+}
+
 // ApiCategorySpec defines the desired state of ApiCategory
 type ApiCategorySpec struct {
 	// LabelValue is the name of the API category in the specification.
@@ -39,16 +74,11 @@ type ApiCategorySpec struct {
 	// +kubebuilder:default:=true
 	MustHaveGroupPrefix bool `json:"mustHaveGroupPrefix,omitempty"`
 
+	// Linting configures OAS specification linting for APIs in this category.
+	// +optional
 	Linting *LintingConfig `json:"linting,omitempty"`
 }
 
-type LintingConfig struct {
-	// Enabled indicates whether linting is enabled for this API category.
-	Enabled bool `json:"enabled,omitempty"`
-	// Ruleset specifies the ruleset to use for linting.
-	Ruleset string `json:"ruleset,omitempty"`
-}
-
 type AllowTeamsConfig struct {
 	// Categories defines the list of team categories that are allowed to use this API category.
 	// If empty, all team categories are allowed.

api/config/crd/bases/api.cp.ei.telekom.de_apicategories.yaml

@@ -80,14 +80,36 @@ spec:
                 minLength: 1
                 type: string
               linting:
+                description: Linting configures OAS specification linting for APIs
+                  in this category.
                 properties:
-                  enabled:
-                    description: Enabled indicates whether linting is enabled for
-                      this API category.
-                    type: boolean
+                  mode:
+                    default: Block
+                    description: |-
+                      Mode controls how linting failures affect API creation.
+                      "Block" (default) prevents Api creation on failure; "Warn" allows it but surfaces issues.
+                    enum:
+                    - Block
+                    - Warn
+                    - None
+                    type: string
                   ruleset:
-                    description: Ruleset specifies the ruleset to use for linting.
+                    description: |-
+                      Ruleset is the name of the linter ruleset to apply.
+                      If set, it is passed as a URL-encoded query parameter to the linter API.
                     type: string
+                  whitelistedBasepaths:
+                    description: |-
+                      WhitelistedBasepaths is a list of API basepaths that are exempt from linting.
+                      APIs whose basePath matches an entry here will skip linting even when linting is configured.
+                      Each entry must start with a leading slash.
+                    items:
+                      pattern: ^/
+                      type: string
+                    type: array
+                    x-kubernetes-list-type: set
+                required:
+                - ruleset
                 type: object
               mustHaveGroupPrefix:
                 default: true

api/internal/controller/apicategory_controller_test.go

@@ -5,7 +5,7 @@
 package controller
 
 import (
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
@@ -34,10 +34,6 @@
 				Names:      []string{"test-team"},
 			},
 			MustHaveGroupPrefix: true,
-			Linting: &apiv1.LintingConfig{
-				Enabled: false,
-				Ruleset: "owasp",
-			},
 		},
 	}
 }

rover-server/cmd/main.go

@@ -51,7 +51,7 @@
 	s := server.Server{
 		Config:              cfg,
 		Log:                 log.Log,
-		ApiSpecifications:   controller.NewApiSpecificationController(stores),
+		ApiSpecifications:   controller.NewApiSpecificationController(stores, cfg.OasLinting),
 		Rovers:              controller.NewRoverController(stores),
 		Roadmaps:            controller.NewRoadmapController(stores),
 		EventSpecifications: controller.NewEventSpecificationController(stores),
@@ -64,7 +64,7 @@
 	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
 	go func() {
 		err := app.Listen(cfg.Address)
 		if err != nil && err != http.ErrServerClosed {
 			log.Log.Error(err, "Failed to start server")
 		}
 	}()

rover-server/config/rbac/role.yaml

@@ -18,6 +18,7 @@ rules:
 - apiGroups:
   - api.cp.ei.telekom.de
   resources:
+  - apicategories
   - apiexposures
   - apis
   - apisubscriptions

rover-server/internal/config/config.go

@@ -6,6 +6,7 @@ package config
 
 import (
 	"strings"
+	"time"
 
 	"github.com/pkg/errors"
 	"github.com/spf13/viper"
@@ -16,6 +17,15 @@ type ServerConfig struct {
 	Security    SecurityConfig    `json:"security"`
 	Log         LogConfig         `json:"log"`
 	FileManager FileManagerConfig `json:"fileManager"`
+	OasLinting  OasLintingConfig  `json:"oasLinting"`
+}
+
+type OasLintingConfig struct {
+	ErrorMessage string        `json:"errorMessage"`
+	Timeout      time.Duration `json:"timeout"`
+	URL          string        `json:"url"`
+	DashboardURL string        `json:"dashboardURL"`
+	SkipTLS      bool          `json:"skipTLS"`
 }
 
 type SecurityConfig struct {
@@ -72,6 +82,13 @@ func setDefaults() {
 	// FileManager
 	viper.SetDefault("fileManager.skipTLS", true)
 
+	// OAS Linting
+	viper.SetDefault("oasLinting.errorMessage", "Linter scan result contains errors. Please visit the linter UI for details on the RULESET_NAME_PLACEHOLDER ruleset.")
+	viper.SetDefault("oasLinting.timeout", 0) // 0 means block indefinitely until linter responds
+	viper.SetDefault("oasLinting.url", "")
+	viper.SetDefault("oasLinting.dashboardURL", "")
+	viper.SetDefault("oasLinting.skipTLS", false)
+
 	// Database
 	viper.SetDefault("database.filepath", "")        // empty string means in-memory only
 	viper.SetDefault("database.reduceMemory", false) // see common-server docs

rover-server/internal/controller/apilinter.go

@@ -0,0 +1,154 @@
+// Copyright 2025 Deutsche Telekom IT GmbH
+//
+// SPDX-License-Identifier: Apache-2.0
+
+package controller
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/go-logr/logr"
+	apiv1 "github.com/telekom/controlplane/api/api/v1"
+	commonclient "github.com/telekom/controlplane/common-server/pkg/client"
+	"github.com/telekom/controlplane/rover-server/internal/config"
+	"github.com/telekom/controlplane/rover-server/internal/oaslint"
+	roverv1 "github.com/telekom/controlplane/rover/api/v1"
+)
+
+// LintOutcome describes how linting completed.
+type LintOutcome int
+
+const (
+	// LintSkipped means no linting was needed (no config, whitelisted, or hash dedup).
+	LintSkipped LintOutcome = iota
+	// LintCompleted means linting ran synchronously and the result is on apiSpec.Spec.Lint.
+	LintCompleted
+	// LintBlocked means linting ran, the spec failed, and the category mode is Block.
+	LintBlocked
+)
+
+// ApiLinter abstracts the full OAS linting lifecycle: config lookup,
+// whitelists, and execution and should populate apiSpec.Spec.Lint with the result if linting was performed.
+type ApiLinter interface {
+	// Lint performs the full linting lifecycle for an ApiSpecification.
+	// It looks up the linting config from the category list, checks whitelists,
+	// and runs the linter synchronously.
+	Lint(ctx context.Context, apiSpec *roverv1.ApiSpecification, category *apiv1.ApiCategory, specBytes []byte) (LintOutcome, error)
+}
+
+// apiLinterImpl is the production implementation of ApiLinter.
+type apiLinterImpl struct {
+	errorMessage string
+	url          string
+	dashboardURL string
+	httpClient   oaslint.HTTPDoer
+}
+
+// NewApiLinter creates an ApiLinter from the given linting configuration.
+func NewApiLinter(lintCfg config.OasLintingConfig) ApiLinter {
+	return &apiLinterImpl{
+		errorMessage: lintCfg.ErrorMessage,
+		url:          lintCfg.URL,
+		dashboardURL: lintCfg.DashboardURL,
+		httpClient: commonclient.NewHttpClientOrDie(
+			commonclient.WithClientName("oaslint"),
+			commonclient.WithClientTimeout(lintCfg.Timeout),
+			commonclient.WithSkipTlsVerify(lintCfg.SkipTLS),
+		),
+	}
+}
+
+func (l *apiLinterImpl) Lint(ctx context.Context, apiSpec *roverv1.ApiSpecification, category *apiv1.ApiCategory, specBytes []byte) (LintOutcome, error) {
+	log := logr.FromContextOrDiscard(ctx)
+	log.V(1).Info("Looking up linting config", "namespace", apiSpec.Namespace, "name", apiSpec.Name,
+		"category", apiSpec.Spec.Category, "basepath", apiSpec.Spec.BasePath)
+
+	if category == nil {
+		log.V(1).Info("No category provided, skipping linting", "namespace", apiSpec.Namespace, "name", apiSpec.Name)
+		return LintSkipped, nil
+	}
+
+	lintCfg := category.Spec.Linting
+	if lintCfg == nil || l.url == "" || lintCfg.Mode == apiv1.LintingModeNone {
+		log.V(1).Info("No linting config or no URL, skipping linting", "namespace", apiSpec.Namespace, "name", apiSpec.Name)
+		return LintSkipped, nil
+	}
+
+	log.V(1).Info("Linting config found, checking whitelists", "namespace", apiSpec.Namespace, "name", apiSpec.Name)
+	if !l.prepareLinting(lintCfg, apiSpec) {
+		log.V(1).Info("Linting skipped (whitelisted)", "namespace", apiSpec.Namespace, "name", apiSpec.Name)
+		return LintSkipped, nil
+	}
+
+	if err := l.runLint(ctx, apiSpec, lintCfg.Ruleset, specBytes); err != nil {
+		return LintCompleted, err
+	}
+
+	if lintCfg.Mode == apiv1.LintingModeBlock && apiSpec.Spec.Lint != nil && !apiSpec.Spec.Lint.Passed {
+		return LintBlocked, fmt.Errorf("linting failed in block mode: %s", apiSpec.Spec.Lint.Message)
+	}
+
+	return LintCompleted, nil
+}
+
+func (l *apiLinterImpl) prepareLinting(lintCfg *apiv1.LintingConfig, apiSpec *roverv1.ApiSpecification) bool {
+	if isBasepathWhitelisted(lintCfg, apiSpec.Spec.BasePath) {
+		apiSpec.Spec.Lint = &roverv1.LintResult{Passed: true, Message: fmt.Sprintf("The basepath %q is whitelisted", apiSpec.Spec.BasePath)}
+		return false
+	}
+	apiSpec.Spec.Lint = nil
+	return true
+}
+
+func (l *apiLinterImpl) runLint(ctx context.Context, apiSpec *roverv1.ApiSpecification, ruleset string, specBytes []byte) error {
+	log := logr.FromContextOrDiscard(ctx).WithName("linting")
+
+	var opts []oaslint.ExternalLinterOption
+	if ruleset != "" {
+		opts = append(opts, oaslint.WithRuleset(ruleset))
+	}
+	opts = append(opts, oaslint.WithHTTPClient(l.httpClient))
+	linter := oaslint.NewExternalLinter(l.url, opts...)
+
+	result, err := linter.Lint(ctx, specBytes)
+	if err != nil {
+		apiSpec.Spec.Lint = &roverv1.LintResult{
+			Passed:  false,
+			Message: fmt.Sprintf("linter API error: %s", err),
+		}
+		log.Error(err, "OAS linting failed", "namespace", apiSpec.Namespace, "name", apiSpec.Name)
+		return fmt.Errorf("linter API error: %w", err)
+	}
+
+	apiSpec.Spec.Lint = l.buildLintResult(result)
+	if !apiSpec.Spec.Lint.Passed {
+		log.Info("Linting failed", "namespace", apiSpec.Namespace, "name", apiSpec.Name, "message", apiSpec.Spec.Lint.Message)
+	}
+	return nil
+}
+
+func (l *apiLinterImpl) buildLintResult(result *oaslint.LintResult) *roverv1.LintResult {
+	lintResult := &roverv1.LintResult{
+		Passed:  result.Passed,
+		Message: result.Reason,
+	}
+	if l.dashboardURL != "" && result.LinterId != "" {
+		lintResult.DashboardURL = fmt.Sprintf("%s/scans/%s", strings.TrimRight(l.dashboardURL, "/"), result.LinterId)
+	}
+	if !result.Passed {
+		lintResult.Message = strings.ReplaceAll(l.errorMessage, "RULESET_NAME_PLACEHOLDER", result.Ruleset)
+	}
+	return lintResult
+}
+
+// isBasepathWhitelisted checks whether the given basepath is in the category's whitelist.
+func isBasepathWhitelisted(cfg *apiv1.LintingConfig, basepath string) bool {
+	for _, wp := range cfg.WhitelistedBasepaths {
+		if strings.EqualFold(wp, basepath) {
+			return true
+		}
+	}
+	return false
+}