AI-powered compliance policy auditing system that analyzes organizational policies against industry frameworks like SOC 2, ISO 27001, HIPAA, and GDPR.
- Multi-Framework Support: Audit policies against SOC 2, ISO 27001, HIPAA, and GDPR
- AI-Powered Analysis: Uses OpenAI GPT-4 for intelligent policy gap detection
- RESTful API: Comprehensive REST API with OpenAPI/Swagger documentation
- Security First: Rate limiting, authentication, security headers, and HTTPS enforcement
- Resilient: Automatic retry logic with exponential backoff for external services
- Monitoring: Built-in metrics collection and health checks
- Scheduled Compliance: Automated daily compliance reporting and log exports
- Comprehensive Testing: Unit and integration tests with high coverage
- Node.js 18+
- OpenAI API key
- npm or yarn
# Clone the repository
git clone https://github.com/DevilsDev/policy-auditor.git
cd policy-auditor
# Install dependencies
npm install
# Copy environment template
cp .env.example .env
# Edit .env and add your OpenAI API keyEdit .env file with your settings:
OPENAI_API_KEY=your-api-key-here
NODE_ENV=development
PORT=3000
AUTH_REQUIRED=true
AUTH_TOKEN_SECRET=your-secure-secret-min-32-charsSee .env.example for all available configuration options.
# Start API server
npm run server
# Start API server in development mode (with auto-reload)
npm run server:dev
# Run CLI audit
npm start path/to/policy.txt SOC2
# Export logs manually
npm start -- --export-logs# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverageOnce the server is running, visit:
- API Documentation: http://localhost:3000/documentation
- Health Check: http://localhost:3000/v1/health
Analyze a policy document for compliance gaps.
Request:
{
"policyText": "Your policy document text...",
"framework": "SOC2"
}Response:
{
"result": {
"framework": "SOC 2",
"description": "Service Organization Control 2",
"auditDate": "2025-11-09T03:14:00.000Z",
"findingCount": 3,
"findings": [
{
"issue": "Weak access control policy",
"severity": "high",
"sectionSummary": "Section 3.1 lacks MFA requirements",
"recommendedAction": "Implement multi-factor authentication"
}
]
}
}Retrieve application logs (requires authentication).
Query Parameters:
level: Filter by log level (INFO, WARN, ERROR, DEBUG)page: Page number (default: 1)limit: Items per page (default: 10)
Get scheduler health and metrics (requires authentication).
policy-auditor/
├── src/
│ ├── agents/ # AI agent implementations
│ ├── api/ # REST API routes and server
│ ├── config/ # Configuration and framework definitions
│ ├── constants/ # Application constants
│ ├── controllers/ # Business logic controllers
│ ├── cron/ # Scheduled tasks
│ ├── memory/ # In-memory data stores
│ ├── middleware/ # Express/Fastify middleware
│ ├── prompts/ # AI prompt templates
│ ├── services/ # External service clients
│ ├── utils/ # Utility functions
│ └── validators/ # Input validation
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── setup.js # Test configuration
├── logs/ # Application logs
└── docs/ # Additional documentation
- PolicyAuditor Agent: Core agent for policy analysis
- GPTClient: OpenAI API wrapper with retry logic
- Fastify Server: High-performance HTTP server
- Rate Limiter: Request throttling middleware
- Metrics Collector: Application monitoring
- Log Scheduler: Automated compliance reporting
- Never commit
.envfile - Contains sensitive credentials - Use strong secrets - Minimum 32 characters for production
- Enable authentication - Set
AUTH_REQUIRED=truein production - Use HTTPS - Always use HTTPS in production environments
- Rate limiting - Configured by default to prevent abuse
- Input validation - All inputs validated with Zod schemas
The application uses Helmet.js to set security headers:
- Content Security Policy
- X-Frame-Options
- X-Content-Type-Options
- Strict-Transport-Security (HTTPS)
Access metrics at /v1/metrics (requires authentication):
- Request counts and success rates
- Response time statistics
- Error rates and types
- OpenAI API performance
- System uptime
Health endpoint at /v1/health provides:
- Overall system status
- Component health checks
- Uptime information
Structured logging with multiple levels:
- DEBUG: Development debugging
- INFO: General information
- WARN: Warning messages
- ERROR: Error conditions
Logs are:
- Stored in
./logsdirectory - Rotated daily
- Exported to CSV for compliance
- Retained based on
LOG_RETENTION_DAYSsetting
Service Organization Control 2 - Trust Services Criteria
Key Areas:
- Access Controls
- Change Management
- Incident Response
- Vendor Management
- Data Retention & Disposal
- Audit Logging
Information Security Management System
Key Areas:
- Information Security Policy
- Asset Management
- Human Resource Security
- Cryptographic Controls
- Physical Security
- Security Incident Management
Health Insurance Portability and Accountability Act
Key Areas:
- Privacy Rule
- Security Rule
- Access Controls
- Breach Notification
- Audit Controls
- Workforce Training
General Data Protection Regulation
Key Areas:
- Consent Management
- Right to Access
- Right to Erasure
- Data Minimization
- Third-Party Processors
- Breach Notification
- Add framework definition to
src/config/frameworks.js - Create prompt template in
src/prompts/frameworkTemplates.js - Add tests for the new framework
- Update documentation
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
OpenAI API Errors
- Check API key is valid
- Verify account has credits
- Check rate limits
Authentication Failures
- Ensure
AUTH_TOKEN_SECRETis set - Verify token format:
Bearer {token}
Rate Limit Exceeded
- Wait for rate limit window to reset
- Check
RATE_LIMIT_MAXconfiguration - Consider increasing limits for your use case
ISC License - See LICENSE file for details
For issues and questions:
- GitHub Issues: https://github.com/DevilsDev/policy-auditor/issues
- Email: compliance@company.com
- Added comprehensive test suite
- Implemented retry logic with exponential backoff
- Added rate limiting and security headers
- Integrated Swagger/OpenAPI documentation
- Enhanced error handling with custom error types
- Added monitoring and metrics collection
- Improved security with better secret management
- Added HTTPS enforcement capabilities
- Initial release
- Basic policy auditing functionality
- CLI and API interfaces
- Support for SOC 2, ISO 27001, HIPAA, GDPR