README.md

metadata

title: Ey Catalyst
emoji: 📊
colorFrom: yellow
colorTo: purple
sdk: docker
pinned: false
license: mit

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

EY Catalyst - Business Impact Assessment & Risk Management API

An advanced AI-powered FastAPI application for Business Impact Assessment (BIA), threat identification, and risk mitigation analysis. This tool helps organizations identify, assess, and mitigate risks across their business processes using sophisticated AI models.

🚀 Features

• Process Risk Assessment: Generate comprehensive threat analyses for business processes
• Risk Mitigation Planning: Create actionable mitigation strategies with revised risk ratings
• Geographic Threat Assessment: Analyze location-specific threats and risks
• AI-Powered Analysis: Uses advanced language models (Groq/Llama) for intelligent risk assessment
• RESTful API: Easy integration with existing systems and frontends
• Interactive Documentation: Built-in Swagger UI for API exploration

📋 Table of Contents

• Installation
• Configuration
• API Endpoints
• Use Cases
• Request/Response Examples
• Error Handling
• Contributing

🛠️ Installation

Prerequisites

• Python 3.8+
• GROQ API Key (for AI model access)

Setup

1. Clone the repository

   git clone <repository-url>
   cd ey-catalyst
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Set environment variables

   export GROQ_API_KEY=your_groq_api_key_here
   

4. Run the application

   uvicorn app:app --reload --port 8000
   

5. Access the API

   • API Documentation: http://localhost:8000/docs
   • Base URL: http://localhost:8000

⚙️ Configuration

Environment Variables

Variable	Description	Required
GROQ_API_KEY	API key for Groq language model service	Yes

Supported Models

• llama3-8b-8192: Primary model for risk analysis and threat assessment

🔗 API Endpoints

1. Process Threat Generation

Endpoint: POST /api/generate-threats

Generates comprehensive threat assessments for business processes.

Use Cases:

• Business continuity planning
• Risk register development
• Process vulnerability assessment
• Compliance risk analysis

Request Body:

{
  "processName": "Financial Transaction Processing",
  "department": "Finance",
  "description": "Handles all daily banking transactions",
  "owner": "John Doe",
  "businessContext": "Supports daily liquidity tracking",
  "rto": "1hour",
  "mtpd": "24hours",
  "minTolerableDowntime": "15minutes"
}

Response:

{
  "threats": [
    {
      "id": 1,
      "name": "Cyber Attack",
      "description": "Malicious attack disrupting core operations",
      "likelihood": 3,
      "impact": 4,
      "category": "Security",
      "mitigation": "Use firewalls and real-time monitoring"
    }
  ]
}

2. Risk Mitigation Analysis

Endpoint: POST /api/risk-mitigation

Provides mitigation strategies and revised risk assessments for identified threats.

Use Cases:

• Risk treatment planning
• Control effectiveness assessment
• Residual risk calculation
• Mitigation cost-benefit analysis

Request Body:

{
  "responses": [
    {
      "category": "Fire",
      "question": "Is the data centre equipped with an appropriate fire suppression system?",
      "user_answer": "We only have a few handheld fire extinguishers, and there's no automated system."
    },
    {
      "category": "Cybercrime",
      "question": "Is there a well-documented and tested incident response plan?",
      "user_answer": "There is a response plan but it hasn't been tested in the last 2 years."
    }
  ]
}

Response:

{
  "risk_analysis": {
    "risk_id": "RISK-001",
    "category": "Fire",
    "question": "Is the data centre equipped with an appropriate fire suppression system?",
    "user_answer": "We only have a few handheld fire extinguishers, and there's no automated system.",
    "risk_name": "Absence of automated fire suppression system",
    "identified_threat": "Increased risk of fire damage and personnel danger due to lack of automatic suppression systems.",
    "likelihood": "High",
    "impact": "Severe",
    "risk_value": 9,
    "residual_risk": "Critical",
    "current_control_description": "Only basic handheld extinguishers are available; no active fire suppression in place.",
    "current_control_rating": "Poor",
    "business_unit": "Facilities",
    "risk_owner": "Fire Safety Officer",
    "timeline": "Immediate",
    "mitigation_plan": "Install automated suppression systems like FM200 or Inergen and integrate with fire alarms.",
    "summary": {
      "risk_classification_summary": "This is a critical fire safety risk with a high likelihood and severe impact. It requires immediate action.",
      "mitigation_suggestions": [
        "Deploy automated gas-based fire suppression systems.",
        "Conduct fire safety training and drills.",
        "Regularly inspect and maintain suppression systems."
      ],
      "risk_trends": {
        "top_category": "Fire",
        "risk_severity": "Critical",
        "observations": [
          "Many facilities lack automated fire suppression.",
          "High fire risks stem from outdated or manual systems.",
          "Immediate remediation is crucial to prevent major incidents."
        ]
      }
    }
  }
}

3. Geographic Threat Assessment

Endpoint: POST /bia/threat-assessment

Analyzes location-specific threats and geopolitical risks.

Use Cases:

• International expansion risk assessment
• Supply chain geographical risk analysis
• Office location security evaluation
• Political stability assessment

Request Body:

{
  "message": "Our company is planning to establish operations in Southeast Asia, specifically in Singapore and Bangkok."
}

Response:

{
  "place": "Southeast Asia (Singapore, Bangkok)",
  "threats": [
    {
      "name": "Political Instability",
      "likelihood": 2,
      "severity": 4,
      "impact": "Potential disruption to business operations",
      "threat_rating": 8
    }
  ]
}

4. Impact Analysis (Placeholder)

Endpoint: POST /bia/impact-analysis

Reserved for future Business Impact Analysis functionality.

🎯 Use Cases

1. Enterprise Risk Management

Scenario: Large corporation conducting annual risk assessment

Process:

1. Use /api/generate-threats for each critical business process
2. Consolidate identified threats into risk register
3. Use /api/risk-mitigation to develop treatment plans
4. Monitor and update mitigation strategies quarterly

Benefits:

• Comprehensive threat identification
• Consistent risk assessment methodology
• Actionable mitigation strategies
• Regulatory compliance support

2. Business Continuity Planning

Scenario: Financial services firm developing BCP

Process:

1. Map critical processes and dependencies
2. Generate threat assessments using AI analysis
3. Determine recovery objectives (RTO/MTPD)
4. Develop mitigation and recovery strategies

Benefits:

• Reduced business disruption
• Faster recovery times
• Improved stakeholder confidence
• Regulatory compliance

3. Vendor Risk Assessment

Scenario: Evaluating third-party service providers

Process:

1. Assess vendor-specific threats and controls
2. Generate mitigation recommendations
3. Calculate residual risk post-mitigation
4. Develop ongoing monitoring strategies

Benefits:

• Informed vendor selection
• Reduced supply chain risks
• Clear accountability frameworks
• Continuous risk monitoring

4. Geographic Expansion Planning

Scenario: Multinational expanding to new markets

Process:

1. Use geographic threat assessment for target locations
2. Evaluate political, economic, and security risks
3. Develop location-specific risk mitigation plans
4. Establish local risk monitoring capabilities

Benefits:

• Informed market entry decisions
• Reduced operational risks
• Better resource allocation
• Enhanced stakeholder confidence

📊 Request/Response Examples

Complete Process Risk Assessment

Request:

curl -X POST "http://localhost:8000/api/generate-threats" \
  -H "Content-Type: application/json" \
  -d '{
    "processName": "Customer Data Processing",
    "department": "IT Operations",
    "description": "Manages customer personal and financial data",
    "owner": "Data Protection Officer",
    "businessContext": "Critical for customer service and compliance",
    "rto": "2hours",
    "mtpd": "8hours",
    "minTolerableDowntime": "30minutes"
  }'

Response:

{
  "threats": [
    {
      "id": 1,
      "name": "Data Breach",
      "description": "Unauthorized access to customer personal and financial data could result in regulatory fines, legal action, and reputational damage",
      "likelihood": 3,
      "impact": 5,
      "category": "Security",
      "mitigation": "Implement encryption, access controls, and regular security audits"
    },
    {
      "id": 2,
      "name": "System Outage",
      "description": "Hardware or software failure could disrupt customer service operations beyond acceptable RTO",
      "likelihood": 4,
      "impact": 4,
      "category": "Operational",
      "mitigation": "Deploy redundant systems and automated failover mechanisms"
    }
  ]
}

Risk Mitigation Planning

Request:

curl -X POST "http://localhost:8000/api/risk-mitigation" \
  -H "Content-Type: application/json" \
  -d '{
    "responses": [
      {
        "category": "Cybercrime",
        "question": "Is there a well-documented and tested incident response plan?",
        "user_answer": "There is a response plan but it hasn't been tested in the last 2 years."
      }
    ]
  }'

Response:

{
  "risk_analysis": {
    "risk_id": "RISK-002",
    "category": "Cybercrime",
    "question": "Is there a well-documented and tested incident response plan?",
    "user_answer": "There is a response plan but it hasn't been tested in the last 2 years.",
    "risk_name": "Outdated incident response planning",
    "identified_threat": "Delayed or ineffective response to cyber incidents due to outdated procedures",
    "likelihood": "High",
    "impact": "Severe",
    "risk_value": 8,
    "residual_risk": "High",
    "current_control_description": "Outdated incident response plan without recent testing",
    "current_control_rating": "Poor",
    "business_unit": "Information Technology",
    "risk_owner": "CISO",
    "timeline": "Immediate",
    "mitigation_plan": "Update incident response plan, conduct regular testing, and implement automated threat detection",
    "summary": {
      "risk_classification_summary": "High-risk cybersecurity vulnerability requiring prompt remediation",
      "mitigation_suggestions": [
        "Update and test incident response plan quarterly",
        "Implement automated threat detection systems",
        "Conduct regular cybersecurity training"
      ],
      "risk_trends": {
        "top_category": "Cybercrime",
        "risk_severity": "High",
        "observations": [
          "Incident response plans are outdated across organization",
          "Limited testing reduces effectiveness of responses",
          "Regular plan updates and testing are essential"
        ]
      }
    }
  }
}

📮 Postman Setup Guide

Prerequisites

• Postman installed (download from postman.com)
• API server running locally on http://localhost:8000

1. Process Threat Generation Endpoint

Create New Request:

• Method: POST
• URL: http://localhost:8000/api/generate-threats
• Name: "Generate Process Threats"

Headers:

• Key: Content-Type
• Value: application/json

Request Body (raw JSON):

{
  "processName": "Financial Transaction Processing",
  "department": "Finance",
  "description": "Handles all daily banking transactions and payment processing",
  "owner": "John Smith",
  "businessContext": "Critical for daily operations and customer payments",
  "rto": "1hour",
  "mtpd": "24hours",
  "minTolerableDowntime": "15minutes"
}

Alternative Test Cases:

IT Infrastructure Process:

{
  "processName": "Email Server Management",
  "department": "IT Operations",
  "description": "Manages corporate email infrastructure and communications",
  "owner": "IT Manager",
  "businessContext": "Essential for internal and external communications",
  "rto": "4hours",
  "mtpd": "48hours",
  "minTolerableDowntime": "1hour"
}

HR Process:

{
  "processName": "Payroll Processing",
  "department": "Human Resources",
  "description": "Monthly salary and benefits processing for all employees",
  "owner": "Payroll Manager",
  "businessContext": "Critical for employee satisfaction and legal compliance",
  "rto": "8hours",
  "mtpd": "72hours",
  "minTolerableDowntime": "24hours"
}

2. Risk Mitigation Analysis Endpoint

Create New Request:

• Method: POST
• URL: http://localhost:8000/api/risk-mitigation
• Name: "Risk Mitigation Analysis"

Headers:

• Key: Content-Type
• Value: application/json

Request Body (raw JSON):

{
  "responses": [
    {
      "category": "Fire",
      "question": "Is the data centre equipped with an appropriate fire suppression system?",
      "user_answer": "We only have a few handheld fire extinguishers, and there's no automated system."
    }
  ]
}

Multiple Risk Questions Example:

{
  "responses": [
    {
      "category": "Fire",
      "question": "Is the data centre equipped with an appropriate fire suppression system?",
      "user_answer": "We only have a few handheld fire extinguishers, and there's no automated system."
    },
    {
      "category": "Cybercrime", 
      "question": "Is there a well-documented and tested incident response plan?",
      "user_answer": "There is a response plan but it hasn't been tested in the last 2 years."
    }
  ]
}

Additional Risk Categories Examples:

{
  "responses": [
    {
      "category": "Physical Security",
      "question": "Are there adequate access controls for all critical facilities?",
      "user_answer": "We have basic card access but no multifactor authentication or visitor management."
    }
  ]
}

{
  "responses": [
    {
      "category": "Business Continuity",
      "question": "Do you have tested backup systems for critical operations?",
      "user_answer": "We have backups but testing is irregular and there's no formal recovery procedure documented."
    }
  ]
}

3. Geographic Threat Assessment Endpoint

Create New Request:

• Method: POST
• URL: http://localhost:8000/bia/threat-assessment
• Name: "Geographic Threat Assessment"

Headers:

• Key: Content-Type
• Value: application/json

Request Body (raw JSON):

{
  "message": "Our company is planning to establish operations in Southeast Asia, specifically in Singapore and Bangkok."
}

Alternative Geographic Scenarios:

European Expansion:

{
  "message": "We are considering opening offices in Eastern Europe, particularly in Poland, Czech Republic, and Hungary for our manufacturing operations."
}

Middle East Assessment:

{
  "message": "Risk assessment needed for expanding our financial services into the Middle East, focusing on UAE, Saudi Arabia, and Qatar."
}

Latin America Supply Chain:

{
  "message": "Evaluating supply chain risks across Latin America including Mexico, Brazil, Argentina, and Colombia for our automotive parts business."
}

African Market Entry:

{
  "message": "Planning to enter African markets for telecommunications infrastructure, targeting South Africa, Nigeria, and Kenya."
}

4. Postman Collection Setup

Create a Collection:

1. Click "New" → "Collection"
2. Name: "EY Catalyst Risk Management API"
3. Add all three requests to this collection

Environment Variables:

1. Create environment: "EY Catalyst Local"
2. Add variable:
   • Variable: base_url
   • Initial Value: http://localhost:8000
   • Current Value: http://localhost:8000

Update URLs to use environment:

• Change URLs to: {{base_url}}/api/generate-threats
• Change URLs to: {{base_url}}/api/risk-mitigation
• Change URLs to: {{base_url}}/bia/threat-assessment

5. Testing Workflow

Recommended Testing Sequence:

1. Start with Threat Generation:

   • Test with different business processes
   • Verify threat categories and severity levels
   • Note generated threat IDs for follow-up

2. Follow with Risk Mitigation:

   • Use threats from step 1 or create new risk scenarios
   • Test single and multiple risk items
   • Verify mitigation plans are actionable

3. Conclude with Geographic Assessment:

   • Test various global regions
   • Compare risk profiles across locations
   • Validate threat ratings and categories

6. Expected Response Validation

Threat Generation Response Structure:

{
  "threats": [
    {
      "id": 1,
      "name": "string",
      "description": "string",
      "likelihood": 1-5,
      "impact": 1-5,
      "category": "string",
      "mitigation": "string"
    }
  ]
}

Risk Mitigation Response Structure:

{
  "risk_analysis": {
    "risk_id": "RISK-XXX",
    "category": "string",
    "question": "string",
    "user_answer": "string",
    "risk_name": "string",
    "identified_threat": "string",
    "likelihood": "string",
    "impact": "string",
    "risk_value": 1-10,
    "residual_risk": "string",
    "current_control_description": "string",
    "current_control_rating": "string",
    "business_unit": "string",
    "risk_owner": "string",
    "timeline": "string",
    "mitigation_plan": "string",
    "summary": {
      "risk_classification_summary": "string",
      "mitigation_suggestions": ["string", "string", "string"],
      "risk_trends": {
        "top_category": "string",
        "risk_severity": "string",
        "observations": ["string", "string", "string"]
      }
    }
  }
}

Geographic Assessment Response Structure:

{
  "place": "string",
  "threats": [
    {
      "name": "string",
      "likelihood": 1-5,
      "severity": 1-5,
      "impact": "string",
      "threat_rating": 1-25
    }
  ]
}

7. Troubleshooting

Common Issues:

• Server not running: Ensure uvicorn app:app --reload is active
• Port conflicts: Check if port 8000 is available
• JSON validation errors: Verify request body format
• Missing headers: Confirm Content-Type: application/json

Success Indicators:

• Status Code: 200 OK
• Response contains expected JSON structure
• AI-generated content in responses
• Fallback responses when AI is unavailable

🚨 Error Handling

Common Error Responses

400 Bad Request:

{
  "detail": "Invalid request format or missing required fields"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "processName"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

500 Internal Server Error:

{
  "detail": "AI service temporarily unavailable. Fallback response provided."
}

Fallback Mechanisms

The API includes intelligent fallback responses when AI services are unavailable:

• Threat Generation: Returns common business process threats
• Risk Mitigation: Provides category-based mitigation strategies
• Geographic Assessment: Returns general location risk factors

🔧 Technical Architecture

Components

1. FastAPI Framework: RESTful API with automatic documentation
2. Pydantic Models: Request/response validation and serialization
3. Groq Integration: AI-powered analysis using Llama models
4. Fallback Logic: Intelligent responses when AI is unavailable
5. JSON Processing: Robust parsing of AI-generated responses

Security Considerations

• API Key Management: Secure handling of external service credentials
• Input Validation: Comprehensive request validation using Pydantic
• Error Handling: Graceful degradation with meaningful error messages
• Rate Limiting: Consider implementing for production deployments

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the API documentation at /docs

---

Built with ❤️ for enterprise risk management and business continuity