API Documentation with Additional Endpoints
Base URL
https://riskcognizance.com/api/
All requests require authentication using a valid API token. Obtain a token by following the authentication process outlined in the platform documentation.
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:
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:
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.