PolicyIQ
Enriching Corgea with Business Context through Policies
Prerequisite You have completed a scan, and you have PolicyIQ enabled. Reach out to your Corgea contact to enable PolicyIQ.
Corgea comes pre-configured with a comprehensive set of policies designed to provide immediate value and maximize your security analysis experience. These built-in policies cover common security patterns, frameworks, and infrastructure setups.
You can further customize and extend these policies to enrich the platform with additional business, network, and environmental context to improve the accuracy of vulnerability detection, false positive identification, and fix generation. By providing this context through policies, you can help Corgea better understand your specific security requirements and infrastructure.
Important Policy Behaviors
Before diving into policy structure, there are some key behaviors to understand:
-
Policy Application: New policies only take effect on new scans - they won’t retroactively affect existing results.
-
Policy Precedence:
- More specific policies take precedence over general policies for false positive detection and fixes
- For example, a SSRF-specific false positive policy would override a general false positive policy
- Customer-defined policies always override Corgea’s native policies
-
Policy Grouping: For scanning policies, it’s recommended to group related security concerns together rather than creating individual policies. For example:
- Group authentication, authorization, and permission handling together
- Combine related data validation checks
- Bundle associated security control verifications This approach yields better results as these security concerns often overlap and interact.
Policy Structure
A well-structured policy should include the following components:
-
Policy Type: Specify the type of policy you’re creating, such as BLAST (detecting vulnerabilities), False Positive (identifying false positives), or Fix (suggesting code fixes).
-
Business Context: Provide detailed information about your:
- Business domain and requirements
- Network architecture and security controls
- Environment-specific configurations
- Data classification and handling requirements
- Compliance requirements (e.g., PCI, HIPAA, GDPR)
-
Description: Clear instructions incorporating your context, including:
- Specific vulnerability patterns in your environment
- Code examples relevant to your architecture
- How issues should be handled given your infrastructure
-
Vulnerability Types (CWEs): Choose which types of security vulnerabilities this policy should handle, based on your risk profile.
-
Scope: Select which projects to apply this policy to, allowing for environment-specific policies.
Policy Best Practices
When writing policies, follow these best practices to provide effective context:
-
Be Specific About Your Environment: Detail your infrastructure, security controls, and compensating controls.
-
Include Business Logic: Explain business-specific validation rules, data flows, and security requirements.
-
Describe Security Architecture: Document your security layers, trust boundaries, and protection mechanisms.
-
Define Data Context: Specify how different types of data should be handled in your environment.
-
Document Exceptions: Note any legitimate business cases for apparent security issues.
Examples
When creating policy examples, follow these tips to make them more effective:
-
Use Multiple Examples: Include 3-5 diverse examples for each policy type to:
- Show different use cases and scenarios
- Cover edge cases specific to your environment
- Demonstrate varying levels of complexity
- Illustrate different security controls and compensating measures
-
Make Examples Relevant: Ensure your examples:
- Reflect your actual infrastructure and architecture
- Include real security controls you use
- Reference your specific tools and frameworks
- Match your development patterns and practices
-
Structure Examples Clearly: Format your examples with:
- Clear section headers and labels
- Consistent formatting and indentation
- Detailed comments explaining key points
- Tags to separate different components
-
Include Context: Each example should provide:
- The specific business scenario
- Relevant infrastructure details
- Security controls in place
- Expected behavior and outcomes
Below are example policies demonstrating these principles:
BLAST Policy Example
Policy Type: BLAST
False Positive Policy Example
Policy Type: False Positive
Fix Policy Example
Here’s an example of a Fix policy that uses a custom middleware to protect against XSS vulnerabilities:
Policy Type: Fix
By providing this context, Corgea can generate fixes that properly integrate with your custom security middleware and follow your secure coding guidelines for XSS protection.
Policy Type: Fix
Providing rich context about your business environment, security controls, and infrastructure helps Corgea deliver more accurate and relevant security analysis tailored to your specific needs.
Corgea Policy YAML Configuration Support
Customers can now define security policies for their projects using a corgea.yaml
file. This configuration file enables the specification of detailed security policies, such as:
- Specific CWE identifiers
- Policies tailored to sub-folders
- Testing new policies on a separate branch
This feature is available with the Scale
or Enterprise
plan and requires additional enablement. Please contact us at https://corgea.com/contact for more information.
For reference, you can view an example repository here: Example Repository. You can have - Main Policies for general policy. Examples of sub-folder specific policies can be found in sub-folders like:
These configurations help identify vulnerabilities by considering the context of each folder’s responsibilities. This is particularly useful for monorepos, allowing developers to configure the right context.
Workflow for Updating corgea.yaml
Create Branch and Trigger Scan
Create a new branch with the corgea.yaml file and open a pull request. This will automatically trigger a scan on the branch. Alternatively, you can manually trigger a scan from the project page.
Review Policy File
Go to the PoliciesIQ page, where you will find a section labeled Policy File in Repos
.
Review Policies from Policy File
Click on the section to review the specific policies generated by the corgea.yaml file.
click on `Related issue'
Click on Related Issue
column to see issues triggered from this policy.
Update and Experiment or Merge Your PR
Make further modifications until the results meet your expectations, then merge your pull request to include the corgea.yaml file in the main branch.
Basic configuration for corgea.yaml
Basic configuration of corgea.yaml looks like this :
type
: type of policy. This can be one of “scan”, “false_positive”, “fix”description
contents of policy. Explain additional context or internal security guidelines to tailor security vulnerabilities findings.
Advanced configuration for corgea.yaml
Optionally, you can add these fields
cwes
: Only applicable to “fix”, or “false_positive”. It can apply specific policy to specific cwes. As an example,
excludes
: If you want to exclude some paths for a specific policy scan, you can list those files using a glob expression.
ignore_paths
: If you want to exclude folders globally from all scans, you can specify them here. (Note: these file paths are ignored from all scans, not just a specific policy.)
path
: Instead of having separate corgea.yaml files under sub-folders, you can manage everything centrally by setting path.
As an example of mini-juice-shop, you can have one corgea.yaml like this
Once you trigger a scan on a branch with central yaml,
On the PolicyIQ page, you will see five policies generated.
You can view all the different policies with their respective paths.