background

API Doc

API Documentation with Additional Endpoints

Base URL

https://riskcognizance.com/api/

Authentication

All requests require authentication using a valid API token. Obtain a token by following the authentication process outlined in the platform documentation.

Authentication Endpoints

1. Okta Authentication (SAML)

Endpoint: POST https://riskcognizance.com/api/okta/authentication

Description: Authenticate users via Okta using SAML for single sign-on (SSO).

Parameters:

saml_request: The SAML request payload.

relay_state: Optional relay state parameter.

2. Office 365/Azure Authentication

Endpoint: POST

https://riskcognizance.com/api/office365/authentication

Description: Authenticate users with Microsoft Office 365/Azure Active Directory.

Parameters:

email: Office 365/Azure email.

password: User’s password.

3. OneLogin Authentication (SAML)

Endpoint: POST https://riskcognizance.com/api/onelogin/authentication

Description: Authenticate users via OneLogin using SAML for SSO.

Parameters:

saml_request: The SAML request payload.

relay_state: Optional relay state parameter.

4. Google Authentication

Endpoint: POST https://riskcognizance.com/api/google/authentication

Description: Authenticate users via Google Accounts.

Parameters:

email: Google account email.

password: User’s password.

Core API Endpoints

1. Ransomware Susceptibility Report

Endpoint: GET https://riskcognizance.com/api/ransomware/susceptibility-report

Description: Generates a detailed report on the organization's susceptibility to ransomware attacks.

Parameters:

organization_id (Required): Unique identifier for the organization.

severity_filter (Optional): Filters results by susceptibility severity (e.g., High, Medium, Low).

date_range (Optional): Fetches reports for a specific time period (format: YYYY-MM-DD).

include_remediation (Optional): Boolean flag indicating inclusion of remediation recommendations.

Response:

200 OK: Ransomware Susceptibility Report generated successfully.

400 Bad Request: Invalid organization ID, date range, or parameter combination.

401 Unauthorized: Missing or invalid authentication token.

404 Not Found: Organization not found or report unavailable.

500 Internal Server Error: An error occurred while generating the report.

Example Request:

GET https://riskcognizance.com/api/ransomware/susceptibility-report?organization_id=12345&severity_filter=High&date_range=2024-01-01,2024-10-11

 

Example Response:

JSON

{

    "organization_id": "12345",

    "overall_susceptibility": "High",

    "vulnerable_assets": [

        {

            "asset_id": "789",

            "risk_factor": "Unpatched software",

            "severity": “Critical”

        },

        // ... other vulnerable assets

    ],

    "recommended_actions": [

        "Patch all systems with outdated software.",

        “Close unused network ports and set up a firewall.”

    ],

    "date_generated": “2024-10-11”

}

 

2. Risk Register Reporting

Endpoint: GET https://riskcognizance.com/api/risk-register/report

Description: Generates a report of all active and archived risks within the organization's risk register.

Parameters:

organization_id (Required): Unique identifier for the organization.

risk_type (Optional): Filters by risk type (e.g., Operational, Financial, Cybersecurity).

risk_status (Optional): Filters by risk status (e.g., Open, Mitigated, Closed).

severity (Optional): Filters by risk severity (e.g., High, Medium, Low).

date_range (Optional): Fetches risks registered within a specific period (format: YYYY-MM-DD).

Response:

200 OK: Risk Register Report generated successfully.

400 Bad Request: Invalid organization ID, date range, or parameter combination.

401 Unauthorized: Missing or invalid authentication token.

404 Not Found: No risks found matching the criteria.

500 Internal Server Error: Server error while generating the report.

Example Request:

GET https://riskcognizance.com/api/risk-register/report?organization_id=12345&risk_type=Cybersecurity&severity=High

 

Example Response:

JSON

{

    "organization_id": "54321",

    "risks": [

        {

            "risk_id": "001",

            "risk_type": "Operational",

            "description": "Failure of backup system.",

            "severity": "High",

            "status": "Open",

            "mitigation_actions": "Review backup procedures and install redundant systems.",

            "impact": "Critical",

            "date_logged": “2024-09-01”

        },

        // ... other risks

    ],

    "date_generated": “2024-10-11”

}

Common Responses for Each API Gateway

For every API gateway in Risk Cognizance, standardized responses should include both success and error handling codes. Additionally, security notifications and ticket creation options can be integrated for issue management.

Standard API Response Codes

200 OK: The request was processed successfully.

201 Created: A new resource (e.g., ticket or notification) was created successfully.

204 No Content: The request was successful, but there’s no content to send back.

400 Bad Request: The request is invalid due to missing parameters or incorrect data.

401 Unauthorized: Authentication failed due to missing or invalid API key or token.

403 Forbidden: Access to the resource is denied (e.g., insufficient permissions).

404 Not Found: The resource or endpoint does not exist.

409 Conflict: There’s a conflict with the current state of the resource (e.g., duplicate entry).

500 Internal Server Error: There was a server-side error processing the request.

503 Service Unavailable: The API is temporarily unavailable (e.g., for maintenance).

Security Notifications API

Endpoint:

POST https://riskcognizance.com/api/security/notifications

 

Description:

 This API enables the creation of security alerts and notifications based on detected threats, breaches, or any abnormal system activity. The notification can be pushed to predefined channels, including email, SMS, or integrated platforms like Slack or Microsoft Teams.

Parameters:

notification_type: Type of security event (e.g., breach, phishing attempt, data leak).

severity: Severity of the notification (e.g., critical, high, medium, low).

affected_systems: Affected systems or applications.

details: Detailed description of the security incident.

timestamp: Time the incident was detected.

notification_channel: Channels to send notifications to (email, SMS, Slack, etc.).

Response:

200 OK: Security notification created successfully.

400 Bad Request: Invalid parameters or missing notification details.

Ticket Creation API

Endpoint:

POST https://riskcognizance.com/api/tickets/create

Description:

 Automatically create tickets in the Risk Cognizance GRC platform based on identified issues, security incidents, or compliance violations. These tickets can be integrated into third-party ticketing systems (e.g., Jira, ServiceNow).

Parameters:

issue_type: Type of issue (e.g., vulnerability, compliance violation, audit finding).

priority: Priority of the ticket (e.g., critical, high, medium, low).

description: Detailed description of the issue.

assigned_to: Assignee responsible for addressing the issue.

due_date: Deadline for ticket

Audit Trail API

Endpoint:

GET https://riskcognizance.com/api/audit/trail

Description: Retrieve audit trail records for system actions, user activities, and changes made across the GRC platform. This functionality provides a comprehensive record of user behavior and modifications within the platform.

Parameters:

user_id (Optional): Unique identifier for a specific user. Filters audit logs for that user's actions.

action_type (Optional): Filters audit logs by the type of action performed (e.g., Login, Edit, Delete, Create).

date_range (Optional): Fetches audit logs within a specific time period (format: YYYY-MM-DD).

entity_id (Optional): Unique identifier of an entity (e.g., asset, vendor, risk) to filter the audit logs related to that specific entity.

Response:

200 OK: Audit trail successfully retrieved. Response body includes an array of audit log entries.

400 Bad Request: Invalid parameters or missing filters (e.g., invalid date format, non-existent user ID).

401 Unauthorized: Missing or invalid authentication token.

500 Internal Server Error: Server encountered an error retrieving audit logs.

Example Response:

JSON

{

  "audit_logs": [

    {

      "id": 12345,

      "user_id": 1001,

      "username": "john.doe",

      "action_type": "Edit",

      "entity_type": "Risk",

      "entity_id": 5678,

      "entity_name": "Data Breach Risk",

      "timestamp": "2024-10-11T15:30:00Z",

      "details": “Updated risk severity from High to Medium.”

    },

    {

      "id": 12346,

      "user_id": 1002,

      "username": "jane.smith",

      "action_type": "Create",

      "entity_type": "Asset",

      "entity_id": 9012,

      "entity_name": "New Server",

      "timestamp": "2024-10-10T10:00:00Z",

      "details": “Created a new asset record for a server.”

    },

    // ... other audit log entries

  ]

}

Incident Response API

Endpoint:

ruby

Copy code

POST https://riskcognizance.com/api/incident/report

Description:

Submit detailed incident reports for any security breach or system anomaly, creating automatic security notifications and tickets.

Parameters:

incident_type: Type of incident (e.g., data breach, unauthorized access).

severity: Criticality level of the incident.

affected_assets: List of affected assets (systems, users, etc.).

response_action: Action taken in response to the incident.

incident_time: Time when the incident was detected.

Response:

201 Created: Incident report submitted.

400 Bad Request: Invalid or missing data.

3. Compliance Monitoring API

Endpoint:

ruby

Copy code

POST https://riskcognizance.com/api/compliance/report

Description:

Monitor compliance against various industry standards (HIPAA, GDPR, ISO 27001), and generate automated compliance reports.

Parameters:

compliance_standard: Standard being monitored (HIPAA, GDPR, etc.).

audit_findings: Results of recent audits.

non_compliant_controls: List of controls that are non-compliant.

remediation_plan: Actions to bring controls into compliance.

Response:

200 OK: Compliance report generated.

400 Bad Request: Invalid parameters or missing report details.

4. Attack Surface Management API

Endpoint:

Copy code

POST https://riskcognizance.com/api/attack-surface/monitor

Description:

Monitor an organization’s attack surface for any exposure or vulnerabilities, generating security alerts if necessary.

Parameters:

system_list: List of systems being monitored.

new_exposures: New vulnerabilities detected.

remediation_steps: Steps to mitigate exposures.

Response:

200 OK: Attack surface data successfully processed.

500 Internal Server Error: Failed to retrieve or process data.