rustfs-policy 0.0.3

Policy management for RustFS, providing a framework for defining and enforcing policies across the system.
Documentation

RustFS

RustFS Policy Engine

📖 Overview

RustFS Policy Engine is a sophisticated access control system for the RustFS distributed object storage platform. It provides fine-grained, attribute-based access control (ABAC) with support for complex policy expressions, dynamic evaluation, and AWS IAM-compatible policy syntax.

Note: This is a core submodule of RustFS that provides essential access control and authorization capabilities for the distributed object storage system. For the complete RustFS experience, please visit the main RustFS repository.

✨ Features

🔐 Access Control

  • AWS IAM Compatible: Full support for AWS IAM policy syntax
  • Fine-Grained Permissions: Resource-level and action-level access control
  • Dynamic Policy Evaluation: Real-time policy evaluation with context
  • Conditional Access: Support for complex conditional expressions

📜 Policy Management

  • Policy Documents: Structured policy definition and management
  • Policy Versioning: Version control for policy documents
  • Policy Validation: Syntax and semantic validation
  • Policy Templates: Pre-built policy templates for common use cases

🎯 Advanced Features

  • Attribute-Based Access Control (ABAC): Context-aware access decisions
  • Function-Based Conditions: Rich set of condition functions
  • Principal-Based Policies: User, group, and service account policies
  • Resource-Based Policies: Bucket and object-level policies

🛠️ Integration Features

  • ARN Support: AWS-style Amazon Resource Names
  • Multi-Tenant Support: Isolated policy evaluation per tenant
  • Real-Time Evaluation: High-performance policy evaluation engine
  • Audit Trail: Comprehensive policy evaluation logging

🏗️ Architecture

Policy Engine Architecture

Policy Engine Architecture:
┌─────────────────────────────────────────────────────────────┐
│                    Policy API Layer                         │
├─────────────────────────────────────────────────────────────┤
│   Policy Parser   │   Policy Validator   │   Policy Store   │
├─────────────────────────────────────────────────────────────┤
│              Policy Evaluation Engine                        │
├─────────────────────────────────────────────────────────────┤
│  Condition Functions  │  Principal Resolver  │  Resource Mgr │
├─────────────────────────────────────────────────────────────┤
│              Authentication Integration                      │
└─────────────────────────────────────────────────────────────┘

Policy Decision Flow

Policy Decision Flow:
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Request   │───▶│   Policy    │───▶│   Decision  │
│  (Subject,  │    │  Evaluation │    │  (Allow/    │
│   Action,   │    │   Engine    │    │   Deny/     │
│  Resource)  │    │             │    │  Not Found) │
└─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │
       ▼                   ▼                   ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Context    │    │  Condition  │    │   Audit     │
│ Information │    │ Functions   │    │    Log      │
└─────────────┘    └─────────────┘    └─────────────┘

📦 Installation

Add this to your Cargo.toml:

[dependencies]
rustfs-policy = "0.0.3"

🔧 Usage

🚀 Performance Optimization

Caching Strategy

  • Policy Document Cache: Cache parsed policy documents
  • Evaluation Result Cache: Cache evaluation results for identical requests
  • Condition Cache: Cache condition function results
  • Principal Cache: Cache principal resolution results

Best Practices

  1. Minimize Policy Size: Keep policies as small as possible
  2. Use Specific Actions: Avoid overly broad action patterns
  3. Optimize Conditions: Use efficient condition functions
  4. Cache Frequently Used Policies: Enable policy caching for better performance

🤝 Integration with RustFS

The Policy Engine integrates seamlessly with other RustFS components:

  • IAM Module: Provides policy storage and user/group management
  • ECStore: Implements resource-based access control
  • API Server: Enforces policies on S3 API operations
  • Audit System: Logs policy evaluation decisions
  • Admin Interface: Manages policy documents and templates

📋 Requirements

  • Rust: 1.70.0 or later
  • Platforms: Linux, macOS, Windows
  • Memory: Minimum 1GB RAM for policy caching
  • Storage: Compatible with RustFS storage backend

🐛 Troubleshooting

Common Issues

  1. Policy Parse Errors:

    • Check JSON syntax validity
    • Verify action and resource ARN formats
    • Validate condition function syntax

  2. Policy Evaluation Failures:

    • Check principal resolution
    • Verify resource ARN matching
    • Debug condition function evaluation

  3. Performance Issues:

    • Monitor policy cache hit rates
    • Check policy document sizes
    • Optimize condition functions

Debug Commands

# Validate policy syntax
rustfs-cli policy validate --file policy.json

# Test policy evaluation
rustfs-cli policy test --policy policy.json --user john --action s3:GetObject --resource arn:aws:s3:::bucket/key

# Show policy evaluation trace
rustfs-cli policy trace --policy policy.json --user john --action s3:GetObject --resource arn:aws:s3:::bucket/key

🌍 Related Projects

This module is part of the RustFS ecosystem:

📚 Documentation

For comprehensive documentation, visit:

🔗 Links

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Policy engine architecture and design patterns
  • Policy language syntax and semantics
  • Condition function implementation
  • Performance optimization techniques
  • Security considerations for access control

Development Setup

# Clone the repository
git clone https://github.com/rustfs/rustfs.git
cd rustfs

# Navigate to Policy module
cd crates/policy

# Install dependencies
cargo build

# Run tests
cargo test

# Run policy validation tests
cargo test policy_validation

# Format code
cargo fmt

# Run linter
cargo clippy

💬 Getting Help

📞 Contact

👥 Contributors

This module is maintained by the RustFS security team and community contributors. Special thanks to all who have contributed to making RustFS access control robust and flexible.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

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.