[](https://rustfs.com)
# RustFS Policy Engine
<p align="center">
<strong>Advanced policy-based access control engine for RustFS distributed object storage</strong>
</p>
<p align="center">
<a href="https://github.com/rustfs/rustfs/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/rustfs/rustfs/actions/workflows/ci.yml/badge.svg" /></a>
<a href="https://docs.rustfs.com/en/">📖 Documentation</a>
· <a href="https://github.com/rustfs/rustfs/issues">🐛 Bug Reports</a>
· <a href="https://github.com/rustfs/rustfs/discussions">💬 Discussions</a>
</p>
---
## 📖 Overview
**RustFS Policy Engine** is a sophisticated access control system for the [RustFS](https://rustfs.com) 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](https://github.com/rustfs/rustfs).
## ✨ 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`:
```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
```bash
# 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:
- [RustFS Main](https://github.com/rustfs/rustfs) - Core distributed storage system
- [RustFS IAM](../iam) - Identity and access management
- [RustFS ECStore](../ecstore) - Erasure coding storage engine
- [RustFS Crypto](../crypto) - Cryptographic operations
- [RustFS Utils](../utils) - Utility functions
## 📚 Documentation
For comprehensive documentation, visit:
- [RustFS Documentation](https://docs.rustfs.com)
- [Policy Engine API Reference](https://docs.rustfs.com/policy/)
- [Policy Language Guide](https://docs.rustfs.com/policy-language/)
- [Access Control Guide](https://docs.rustfs.com/access-control/)
## 🔗 Links
- [Documentation](https://docs.rustfs.com) - Complete RustFS manual
- [Changelog](https://github.com/rustfs/rustfs/releases) - Release notes and updates
- [GitHub Discussions](https://github.com/rustfs/rustfs/discussions) - Community support
## 🤝 Contributing
We welcome contributions! Please see
our [Contributing Guide](https://github.com/rustfs/rustfs/blob/main/CONTRIBUTING.md) 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
```bash
# 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
- **Documentation**: [docs.rustfs.com](https://docs.rustfs.com)
- **Issues**: [GitHub Issues](https://github.com/rustfs/rustfs/issues)
- **Discussions**: [GitHub Discussions](https://github.com/rustfs/rustfs/discussions)
- **Security**: Report security issues to <security@rustfs.com>
## 📞 Contact
- **Bugs**: [GitHub Issues](https://github.com/rustfs/rustfs/issues)
- **Business**: <hello@rustfs.com>
- **Jobs**: <jobs@rustfs.com>
- **General Discussion**: [GitHub Discussions](https://github.com/rustfs/rustfs/discussions)
## 👥 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.
<a href="https://github.com/rustfs/rustfs/graphs/contributors">
<img src="https://contrib.rocks/image?repo=rustfs/rustfs" />
</a>
## 📄 License
Licensed under the Apache License, Version 2.0. See [LICENSE](https://github.com/rustfs/rustfs/blob/main/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.
```
---
<p align="center">
<strong>RustFS</strong> is a trademark of RustFS, Inc.<br>
All other trademarks are the property of their respective owners.
</p>
<p align="center">
Made with 🛡️ by the RustFS Security Team
</p>