feat: add security governance policy contracts (#3271)

* feat: add security governance policy contracts

* fix: require signatures for release assets

* docs: update policy verification counts

---------

Co-authored-by: houseme <housemecn@gmail.com>

crates/security-governance/src/lib.rs

@@ -13,8 +13,16 @@
 // limitations under the License.
 
 pub mod admin_matrix;
+pub mod redaction;
+pub mod serde_policy;
+pub mod supply_chain;
 
 pub use admin_matrix::{
     AdminActionRef, AdminRouteAccess, AdminRouteMatrixError, AdminRouteSpec, HttpMethod, PublicRouteKind, RouteRiskLevel,
     validate_admin_route_specs,
 };
+pub use redaction::{RedactionLevel, RedactionPolicyError, RedactionRule, validate_redaction_rules};
+pub use serde_policy::{SerdePolicy, SerdePolicyError, SerdePolicyKind, UnknownFieldPolicy, validate_serde_policies};
+pub use supply_chain::{
+    ArtifactIntegrityPolicy, ArtifactSourceKind, SupplyChainPolicyError, validate_artifact_integrity_policies,
+};

crates/security-governance/src/redaction.rs

@@ -0,0 +1,150 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::collections::BTreeSet;
+
+use thiserror::Error;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum RedactionLevel {
+    Public,
+    Sensitive,
+    Secret,
+}
+
+impl RedactionLevel {
+    pub const fn requires_redaction(self) -> bool {
+        matches!(self, Self::Sensitive | Self::Secret)
+    }
+
+    pub const fn is_secret(self) -> bool {
+        matches!(self, Self::Secret)
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct RedactionRule {
+    field: &'static str,
+    level: RedactionLevel,
+    reason: &'static str,
+}
+
+impl RedactionRule {
+    pub const fn new(field: &'static str, level: RedactionLevel, reason: &'static str) -> Self {
+        Self { field, level, reason }
+    }
+
+    pub const fn field(self) -> &'static str {
+        self.field
+    }
+
+    pub const fn level(self) -> RedactionLevel {
+        self.level
+    }
+
+    pub const fn reason(self) -> &'static str {
+        self.reason
+    }
+}
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum RedactionPolicyError {
+    #[error("redaction rule at index {index} has an empty field")]
+    EmptyField { index: usize },
+
+    #[error("redaction rule at index {index} for {field} has an empty reason")]
+    EmptyReason { index: usize, field: &'static str },
+
+    #[error("duplicate redaction rule for {field}")]
+    DuplicateField { field: &'static str },
+}
+
+pub fn validate_redaction_rules(rules: &[RedactionRule]) -> Result<(), RedactionPolicyError> {
+    let mut fields = BTreeSet::new();
+
+    for (index, rule) in rules.iter().copied().enumerate() {
+        if rule.field.trim().is_empty() {
+            return Err(RedactionPolicyError::EmptyField { index });
+        }
+
+        if rule.reason.trim().is_empty() {
+            return Err(RedactionPolicyError::EmptyReason {
+                index,
+                field: rule.field,
+            });
+        }
+
+        if !fields.insert(rule.field) {
+            return Err(RedactionPolicyError::DuplicateField { field: rule.field });
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validates_redaction_rules() {
+        let rules = [
+            RedactionRule::new("access_key", RedactionLevel::Secret, "credential material"),
+            RedactionRule::new("region", RedactionLevel::Public, "non-sensitive routing metadata"),
+        ];
+
+        assert!(validate_redaction_rules(&rules).is_ok());
+        assert!(rules[0].level().requires_redaction());
+        assert!(rules[0].level().is_secret());
+        assert!(!rules[1].level().requires_redaction());
+        assert_eq!(rules[0].field(), "access_key");
+        assert_eq!(rules[0].reason(), "credential material");
+    }
+
+    #[test]
+    fn rejects_empty_fields() {
+        let rules = [RedactionRule::new(" ", RedactionLevel::Secret, "credential material")];
+
+        let err = validate_redaction_rules(&rules).expect_err("empty field should fail validation");
+
+        assert_eq!(err, RedactionPolicyError::EmptyField { index: 0 });
+    }
+
+    #[test]
+    fn rejects_empty_reasons() {
+        let rules = [RedactionRule::new("access_key", RedactionLevel::Secret, " ")];
+
+        let err = validate_redaction_rules(&rules).expect_err("empty reason should fail validation");
+
+        assert_eq!(
+            err,
+            RedactionPolicyError::EmptyReason {
+                index: 0,
+                field: "access_key"
+            }
+        );
+    }
+
+    #[test]
+    fn rejects_duplicate_fields() {
+        let rules = [
+            RedactionRule::new("access_key", RedactionLevel::Secret, "credential material"),
+            RedactionRule::new("access_key", RedactionLevel::Sensitive, "audit-only secret reference"),
+        ];
+
+        let err = validate_redaction_rules(&rules).expect_err("duplicate field should fail validation");
+
+        assert_eq!(err, RedactionPolicyError::DuplicateField { field: "access_key" });
+    }
+}

crates/security-governance/src/serde_policy.rs

@@ -0,0 +1,172 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::collections::BTreeSet;
+
+use thiserror::Error;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum UnknownFieldPolicy {
+    Deny,
+    Warn,
+    Preserve,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum SerdePolicyKind {
+    StrictIngress,
+    TolerantCompat,
+    PersistentLegacy,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct SerdePolicy {
+    target: &'static str,
+    kind: SerdePolicyKind,
+    unknown_fields: UnknownFieldPolicy,
+}
+
+impl SerdePolicy {
+    pub const fn new(target: &'static str, kind: SerdePolicyKind, unknown_fields: UnknownFieldPolicy) -> Self {
+        Self {
+            target,
+            kind,
+            unknown_fields,
+        }
+    }
+
+    pub const fn target(self) -> &'static str {
+        self.target
+    }
+
+    pub const fn kind(self) -> SerdePolicyKind {
+        self.kind
+    }
+
+    pub const fn unknown_fields(self) -> UnknownFieldPolicy {
+        self.unknown_fields
+    }
+}
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum SerdePolicyError {
+    #[error("serde policy at index {index} has an empty target")]
+    EmptyTarget { index: usize },
+
+    #[error("strict ingress serde policy for {target} must deny unknown fields")]
+    StrictIngressMustDeny { target: &'static str },
+
+    #[error("compat serde policy for {target} must not deny unknown fields")]
+    CompatMustNotDeny { target: &'static str },
+
+    #[error("duplicate serde policy for {target}")]
+    DuplicateTarget { target: &'static str },
+}
+
+pub fn validate_serde_policies(policies: &[SerdePolicy]) -> Result<(), SerdePolicyError> {
+    let mut targets = BTreeSet::new();
+
+    for (index, policy) in policies.iter().copied().enumerate() {
+        if policy.target.trim().is_empty() {
+            return Err(SerdePolicyError::EmptyTarget { index });
+        }
+
+        match (policy.kind, policy.unknown_fields) {
+            (SerdePolicyKind::StrictIngress, UnknownFieldPolicy::Deny) => {}
+            (SerdePolicyKind::StrictIngress, _) => {
+                return Err(SerdePolicyError::StrictIngressMustDeny { target: policy.target });
+            }
+            (SerdePolicyKind::TolerantCompat | SerdePolicyKind::PersistentLegacy, UnknownFieldPolicy::Deny) => {
+                return Err(SerdePolicyError::CompatMustNotDeny { target: policy.target });
+            }
+            (SerdePolicyKind::TolerantCompat | SerdePolicyKind::PersistentLegacy, _) => {}
+        }
+
+        if !targets.insert(policy.target) {
+            return Err(SerdePolicyError::DuplicateTarget { target: policy.target });
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validates_strict_and_compat_policies() {
+        let policies = [
+            SerdePolicy::new("BucketPolicy", SerdePolicyKind::StrictIngress, UnknownFieldPolicy::Deny),
+            SerdePolicy::new("LegacyConfig", SerdePolicyKind::PersistentLegacy, UnknownFieldPolicy::Preserve),
+            SerdePolicy::new("ReplicationRule", SerdePolicyKind::TolerantCompat, UnknownFieldPolicy::Warn),
+        ];
+
+        assert!(validate_serde_policies(&policies).is_ok());
+        assert_eq!(policies[0].target(), "BucketPolicy");
+        assert_eq!(policies[0].kind(), SerdePolicyKind::StrictIngress);
+        assert_eq!(policies[0].unknown_fields(), UnknownFieldPolicy::Deny);
+    }
+
+    #[test]
+    fn rejects_empty_targets() {
+        let policies = [SerdePolicy::new(
+            " ",
+            SerdePolicyKind::StrictIngress,
+            UnknownFieldPolicy::Deny,
+        )];
+
+        let err = validate_serde_policies(&policies).expect_err("empty target should fail validation");
+
+        assert_eq!(err, SerdePolicyError::EmptyTarget { index: 0 });
+    }
+
+    #[test]
+    fn rejects_strict_ingress_without_deny() {
+        let policies = [SerdePolicy::new(
+            "BucketPolicy",
+            SerdePolicyKind::StrictIngress,
+            UnknownFieldPolicy::Warn,
+        )];
+
+        let err = validate_serde_policies(&policies).expect_err("strict ingress should require deny");
+
+        assert_eq!(err, SerdePolicyError::StrictIngressMustDeny { target: "BucketPolicy" });
+    }
+
+    #[test]
+    fn rejects_compat_policy_with_deny() {
+        let policies = [SerdePolicy::new(
+            "LegacyConfig",
+            SerdePolicyKind::PersistentLegacy,
+            UnknownFieldPolicy::Deny,
+        )];
+
+        let err = validate_serde_policies(&policies).expect_err("compat policy should not deny unknown fields");
+
+        assert_eq!(err, SerdePolicyError::CompatMustNotDeny { target: "LegacyConfig" });
+    }
+
+    #[test]
+    fn rejects_duplicate_targets() {
+        let policies = [
+            SerdePolicy::new("BucketPolicy", SerdePolicyKind::StrictIngress, UnknownFieldPolicy::Deny),
+            SerdePolicy::new("BucketPolicy", SerdePolicyKind::TolerantCompat, UnknownFieldPolicy::Warn),
+        ];
+
+        let err = validate_serde_policies(&policies).expect_err("duplicate target should fail validation");
+
+        assert_eq!(err, SerdePolicyError::DuplicateTarget { target: "BucketPolicy" });
+    }
+}

crates/security-governance/src/supply_chain.rs

@@ -0,0 +1,277 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::collections::BTreeSet;
+
+use thiserror::Error;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum ArtifactSourceKind {
+    WorkspaceBuild,
+    ThirdPartyDownload,
+    GeneratedReleaseAsset,
+}
+
+impl ArtifactSourceKind {
+    pub const fn requires_digest(self) -> bool {
+        matches!(self, Self::ThirdPartyDownload | Self::GeneratedReleaseAsset)
+    }
+
+    pub const fn requires_provenance(self) -> bool {
+        matches!(self, Self::GeneratedReleaseAsset)
+    }
+
+    pub const fn requires_signature(self) -> bool {
+        matches!(self, Self::GeneratedReleaseAsset)
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct ArtifactIntegrityPolicy {
+    artifact: &'static str,
+    source: ArtifactSourceKind,
+    digest_required: bool,
+    signature_required: bool,
+    provenance_required: bool,
+}
+
+impl ArtifactIntegrityPolicy {
+    pub const fn new(
+        artifact: &'static str,
+        source: ArtifactSourceKind,
+        digest_required: bool,
+        signature_required: bool,
+        provenance_required: bool,
+    ) -> Self {
+        Self {
+            artifact,
+            source,
+            digest_required,
+            signature_required,
+            provenance_required,
+        }
+    }
+
+    pub const fn artifact(self) -> &'static str {
+        self.artifact
+    }
+
+    pub const fn source(self) -> ArtifactSourceKind {
+        self.source
+    }
+
+    pub const fn digest_required(self) -> bool {
+        self.digest_required
+    }
+
+    pub const fn signature_required(self) -> bool {
+        self.signature_required
+    }
+
+    pub const fn provenance_required(self) -> bool {
+        self.provenance_required
+    }
+}
+
+#[derive(Debug, Error, PartialEq, Eq)]
+pub enum SupplyChainPolicyError {
+    #[error("artifact integrity policy at index {index} has an empty artifact")]
+    EmptyArtifact { index: usize },
+
+    #[error("artifact integrity policy for {artifact} must require a digest")]
+    DigestRequired { artifact: &'static str },
+
+    #[error("artifact integrity policy for {artifact} must require provenance")]
+    ProvenanceRequired { artifact: &'static str },
+
+    #[error("artifact integrity policy for {artifact} must require a signature")]
+    SignatureRequired { artifact: &'static str },
+
+    #[error("duplicate artifact integrity policy for {artifact}")]
+    DuplicateArtifact { artifact: &'static str },
+}
+
+pub fn validate_artifact_integrity_policies(policies: &[ArtifactIntegrityPolicy]) -> Result<(), SupplyChainPolicyError> {
+    let mut artifacts = BTreeSet::new();
+
+    for (index, policy) in policies.iter().copied().enumerate() {
+        if policy.artifact.trim().is_empty() {
+            return Err(SupplyChainPolicyError::EmptyArtifact { index });
+        }
+
+        if policy.source.requires_digest() && !policy.digest_required {
+            return Err(SupplyChainPolicyError::DigestRequired {
+                artifact: policy.artifact,
+            });
+        }
+
+        if policy.source.requires_provenance() && !policy.provenance_required {
+            return Err(SupplyChainPolicyError::ProvenanceRequired {
+                artifact: policy.artifact,
+            });
+        }
+
+        if policy.source.requires_signature() && !policy.signature_required {
+            return Err(SupplyChainPolicyError::SignatureRequired {
+                artifact: policy.artifact,
+            });
+        }
+
+        if !artifacts.insert(policy.artifact) {
+            return Err(SupplyChainPolicyError::DuplicateArtifact {
+                artifact: policy.artifact,
+            });
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn validates_artifact_integrity_policies() {
+        let policies = [
+            ArtifactIntegrityPolicy::new("rustfs-server", ArtifactSourceKind::WorkspaceBuild, false, true, false),
+            ArtifactIntegrityPolicy::new(
+                "rustfs-cli-windows-amd64.zip",
+                ArtifactSourceKind::GeneratedReleaseAsset,
+                true,
+                true,
+                true,
+            ),
+        ];
+
+        assert!(validate_artifact_integrity_policies(&policies).is_ok());
+        assert_eq!(policies[0].artifact(), "rustfs-server");
+        assert_eq!(policies[0].source(), ArtifactSourceKind::WorkspaceBuild);
+        assert!(policies[1].digest_required());
+        assert!(policies[1].signature_required());
+        assert!(policies[1].provenance_required());
+    }
+
+    #[test]
+    fn rejects_empty_artifacts() {
+        let policies = [ArtifactIntegrityPolicy::new(
+            " ",
+            ArtifactSourceKind::WorkspaceBuild,
+            false,
+            false,
+            false,
+        )];
+
+        let err = validate_artifact_integrity_policies(&policies).expect_err("empty artifact should fail validation");
+
+        assert_eq!(err, SupplyChainPolicyError::EmptyArtifact { index: 0 });
+    }
+
+    #[test]
+    fn rejects_external_artifacts_without_digest() {
+        let policies = [ArtifactIntegrityPolicy::new(
+            "third-party-tool",
+            ArtifactSourceKind::ThirdPartyDownload,
+            false,
+            false,
+            false,
+        )];
+
+        let err = validate_artifact_integrity_policies(&policies).expect_err("third-party artifact should require digest");
+
+        assert_eq!(
+            err,
+            SupplyChainPolicyError::DigestRequired {
+                artifact: "third-party-tool"
+            }
+        );
+    }
+
+    #[test]
+    fn rejects_generated_artifacts_without_digest() {
+        let policies = [ArtifactIntegrityPolicy::new(
+            "rustfs-cli-windows-amd64.zip",
+            ArtifactSourceKind::GeneratedReleaseAsset,
+            false,
+            true,
+            true,
+        )];
+
+        let err = validate_artifact_integrity_policies(&policies).expect_err("generated artifact should require digest");
+
+        assert_eq!(
+            err,
+            SupplyChainPolicyError::DigestRequired {
+                artifact: "rustfs-cli-windows-amd64.zip"
+            }
+        );
+    }
+
+    #[test]
+    fn rejects_generated_artifacts_without_provenance() {
+        let policies = [ArtifactIntegrityPolicy::new(
+            "rustfs-cli-windows-amd64.zip",
+            ArtifactSourceKind::GeneratedReleaseAsset,
+            true,
+            true,
+            false,
+        )];
+
+        let err = validate_artifact_integrity_policies(&policies).expect_err("generated artifact should require provenance");
+
+        assert_eq!(
+            err,
+            SupplyChainPolicyError::ProvenanceRequired {
+                artifact: "rustfs-cli-windows-amd64.zip"
+            }
+        );
+    }
+
+    #[test]
+    fn rejects_generated_artifacts_without_signature() {
+        let policies = [ArtifactIntegrityPolicy::new(
+            "rustfs-cli-windows-amd64.zip",
+            ArtifactSourceKind::GeneratedReleaseAsset,
+            true,
+            false,
+            true,
+        )];
+
+        let err = validate_artifact_integrity_policies(&policies).expect_err("generated artifact should require signature");
+
+        assert_eq!(
+            err,
+            SupplyChainPolicyError::SignatureRequired {
+                artifact: "rustfs-cli-windows-amd64.zip"
+            }
+        );
+    }
+
+    #[test]
+    fn rejects_duplicate_artifacts() {
+        let policies = [
+            ArtifactIntegrityPolicy::new("rustfs-server", ArtifactSourceKind::WorkspaceBuild, false, true, false),
+            ArtifactIntegrityPolicy::new("rustfs-server", ArtifactSourceKind::WorkspaceBuild, false, false, false),
+        ];
+
+        let err = validate_artifact_integrity_policies(&policies).expect_err("duplicate artifact should fail validation");
+
+        assert_eq!(
+            err,
+            SupplyChainPolicyError::DuplicateArtifact {
+                artifact: "rustfs-server"
+            }
+        );
+    }
+}