PolicyIQ

​

Important Policy Behaviors

1. Policy Application: New policies only take effect on new scans - they won’t retroactively affect existing results.
2. 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
3. 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

1. 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).
2. 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)
3. 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
4. Vulnerability Types (CWEs): Choose which types of security vulnerabilities this policy should handle, based on your risk profile.
5. Projects: Select which projects to apply this policy to, allowing for environment-specific policies. When Project Access Control is enabled, non-admin users can only create or manage policies for projects they can access and must select at least one accessible project. Company admins can still create policies that apply to all projects.
6. File Pattern (Glob): Optionally limit a policy to matching files (for example, src/**/*.py). Leave empty to apply to all files.
7. Guidance Notes (Optional): Add static guidance for developers, such as internal remediation notes, links to internal standards, or implementation tips. This guidance is shown when viewing issues that were affected by the policy.
8. Instruction Type: Choose how your policy instructions interact with Corgea’s built-in policies:
   • Append to Corgea Default Policy: Adds your policy instructions to Corgea’s built-in policies, preserving both sets of rules. Use this when you want to enhance the default policies with your specific business context, security controls, or environmental details.
   • Replace Corgea Default Policy: Your policy instructions completely override Corgea’s default behavior. Use this when you want full control over how specific scenarios are handled.

​

Policy Playground

• The workspace is split into a policy editor (left) and a test panel (right), with a draggable divider so you can resize the panes to your preference.
• Use Back to Policies in the top toolbar to return to the Policies table at any time.
• Open an existing BLAST or False Positive policy directly in Policy Playground from the Policies table.
• Search the Policies table by Policy ID, name, type, or description to quickly find a policy.
• Editing and saving in Policy Playground updates the policy by creating a new version.
• Instruction Type in the editor is shown as two clearly explained options: Replace Corgea Default Policy or Append to Corgea Default Policy.
• Leave Projects, File Pattern (Glob), or CWEs empty when you want that policy to apply globally.
• When Project Access Control is enabled, scoped users can view policies visible to them, but can only edit or delete policies that apply entirely to projects they can access.

​

Testing a Policy

​

Reviewing Results

​

PR Scan & Comment Rules

• Scan Only runs the pull request scan without posting finding comments.
• Scan & Comment runs the scan and comments on findings that match the rule.
• Severity limits matching to selected severity levels. Leave it empty to match any severity.
• Classification to comment limits comments to selected CWE types. Leave it empty to comment on all matching CWEs.
• Projects and Project Tags define where the rule applies. A rule applies when a project is selected directly or has any selected tag; if both fields are empty, the rule applies to all projects.
• Integrations can further limit the rule to pull requests from selected GitHub, GitLab, or Azure DevOps integrations. Leave it empty to use only the project and project tag scope.

​

Policy Best Practices

1. Be Specific About Your Environment: Detail your infrastructure, security controls, and compensating controls.
2. Include Business Logic: Explain business-specific validation rules, data flows, and security requirements.
3. Describe Security Architecture: Document your security layers, trust boundaries, and protection mechanisms.
4. Define Data Context: Specify how different types of data should be handled in your environment.
5. Document Exceptions: Note any legitimate business cases for apparent security issues.

​

Examples

1. 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
2. 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
3. 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
4. Include Context: Each example should provide:
   • The specific business scenario
   • Relevant infrastructure details
   • Security controls in place
   • Expected behavior and outcomes

​

BLAST Policy Example

Business Context: Our application processes healthcare data behind a secure API gateway that handles encryption. Internal services communicate over a private network with mutual TLS. All database access is through our custom ORM that implements row-level encryption.

Description: Review code considering our infrastructure. Flag potential PHI exposure but account for our API gateway encryption. Consider our network segregation when evaluating internal service communication. Verify proper use of our custom ORM for database access.

Use Cases:
- Detecting direct database access bypassing our ORM
- Identifying services accidentally exposed outside the API gateway
- Finding improper internal service authentication
- Detecting logging of pre-encryption PHI
- Identifying misuse of our security infrastructure

​

False Positive Policy Example

Business Context: Our test environments use sanitized data and mock services. All external services are replaced with stubs. The test network is isolated and all traffic is monitored. We use a custom test framework that simulates security controls.

Description: Consider our test infrastructure when evaluating security issues. Data that appears sensitive is actually sanitized. External service calls are mocked. Network isolation provides additional security layers.

Use Cases:
- Validating test data handling
- Confirming proper use of service mocks
- Verifying test environment isolation
- Checking sanitized data usage
- Validating test security controls

​

Fix Policy Example

Business Context: We use a custom security middleware called "SecureMiddleware" that provides XSS protection, among other security features. All web applications must use this middleware for request handling. The middleware automatically sanitizes user input and encodes output to prevent XSS attacks.

Description: Generate fixes that integrate with our SecureMiddleware for XSS protection. Use the built-in sanitization and encoding functions provided by the middleware. Follow our secure coding guidelines for handling user input and rendering output.

Use Cases:
- Implementing XSS protection using SecureMiddleware
Example: 
```javascript
// Import the SecureMiddleware
import SecureMiddleware from '../middleware/SecureMiddleware';

// Use the middleware for request handling
router.get('/profile', SecureMiddleware.sanitizeInput(), (req, res) => {
  const username = req.query.username; // Username is now sanitized
  
  // Render the profile page with encoded output
  res.render('profile', { 
    username: SecureMiddleware.encodeOutput(username)
  });
});
`` `
In this example, the `SecureMiddleware.sanitizeInput()` function is used to sanitize the `username` parameter from the query string, preventing XSS attacks through user input. The `SecureMiddleware.encodeOutput()` function is then used to encode the `username` value before rendering it in the template, preventing XSS attacks through output rendering.

- Integrating with our centralized security middleware
Example or description: [Add an content]

- Following secure coding practices for user input handling
Example or description: [Add an content]

- Implementing context-specific XSS protection measures
Example or description: [Add an content]

Business Context: We use a custom security framework that provides encryption, authentication, and audit logging. All services must use our security middleware. We have specific requirements for key rotation and cipher selection.

Description: Generate fixes that integrate with our security framework. Use our standard middleware components. Follow our encryption standards and key management practices. Ensure proper audit logging through our centralized system.

Use Cases:
- Implementing framework-compliant security controls
Example or description: [Add an content]

- Integrating with our authentication services
Example or description: [Add an content]

- Setting up proper audit logging
Example or description: [Add an content]

- Configuring encryption using our standards
Example or description: [Add an content]

- Establishing service-to-service authentication
Example or description: [Add an content]

- Implementing environment-specific security measures
Example or description: [Add an content]

​

Prework-generated policies

• Generated policies appear in the Policies table with Source set to Generated By Corgea Prework.
• In scan details, the Policies tab shows all policies applied to that specific scan, including older archived or inactive versions, and lets you open the policy for more details.
• If Policy Review is enabled from Policies > Settings, generated policies are created as Inactive so your team can review and activate them manually.

​

Generating a Policy

1

Click Generate Policy

On the PolicyIQ page, click the Generate Policy button in the top-right area.

2

Fill Out the Generation Form

In the dialog, select a Pattern (e.g., Authentication), choose a Project, and select a Policy Type. Click Generate to start.

3

Wait for Prework to Complete

Corgea runs a Corgea-Prework scan in the background to analyze your project. You can monitor its progress from the Scans page.

4

Review the Generated Policy

Once complete, the generated policy appears in the Policies table. Click on it to review the policy details, including the description populated with real code patterns found in your project.

​

Corgea Policy YAML Configuration Support

• Specific CWE identifiers
• Policies tailored to sub-folders
• Testing new policies on a separate branch

• Frontend Policies
• Backend Policies

​

Workflow for Updating corgea.yaml

1

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.

2

Review Policy File

Go to the PoliciesIQ page, where you will find a section labeled Policy File in Repos.

3

Review Policies from Policy File

Click on the section to review the specific policies generated by the corgea.yaml file.

4

Click on `Associated Issues`

Click on the Associated Issues column to see issues triggered from this policy.

5

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

# This is the corgea YAML file used for defining and managing security policies within applications.
# For more information, visit: https://docs.corgea.app/policies
version: 1  # Specifies the version of the corgea YAML standard being used. Update only if the standard changes.
policies:
  - type: "scan"
    description: >
      This section ensures that all directories and files are thoroughly scanned to detect any security vulnerabilities in the backend code.
      It is essential to identify and address potential issues such as SQL injection, exposure of sensitive data, and unauthorized access.
      Comprehensive scanning helps maintain the security and integrity of the application.

• 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

• instruction_type : Determines how your policy instructions interact with Corgea’s built-in policies. Can be set to "append" or "overwrite". When set to "append", your policy instructions are added to Corgea’s built-in policies, preserving both sets of rules. When set to "overwrite" (default), your policy instructions completely replace Corgea’s default behavior.
• guidance_text : Optional static guidance shown to developers when viewing issues associated with the policy. Use this for team-specific instructions, internal links, or remediation context.

policies:
  - type: "fix"
    instruction_type: "append"
    guidance_text: >
      Use our secure logging utility and do not log raw request payloads.
    description: >
      Additionally, ensure all fixes integrate with our custom SecureMiddleware framework
      and follow our internal security guidelines for key rotation.
    cwes:
      - "CWE-79"  # XSS

• cwes : Only applicable to “fix”, or “false_positive”. It can apply specific policy to specific cwes. As an example,

cwes:
      - "CWE-20"  # CWE-20: Improper Input Validation
      - "CWE-78"  # CWE-78: Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')
      - "CWE-209" # CWE-209: Information Exposure Through an Error Message
      - "CWE-362"
      - "CWE-79"

• excludes : If you want to exclude some paths for a specific policy scan, you can list those files using a glob expression.

   excludes:
      - "config/*"
      - "migrations/*"

• ignore_paths : If you want to exclude folders globally from all scans and new issue creation, you can specify them here. (Note: these file paths are ignored globally, not just for a specific policy. Patterns such as **/vendor/** match at any directory depth.)

   ignore_paths:
      - "test/*"

• path : Instead of having separate corgea.yaml files under sub-folders, you can manage everything centrally by setting path.

# This is the corgea YAML file used for defining and managing security policies within applications.
# For more information, visit: https://docs.corgea.app/policies
version: 1  # Specifies the version of the corgea YAML standard being used. Update only if the standard changes.
policies:
  - type: "scan"
    path: 'backend'
    description: >
      ...
  - type: "scan"
    path: 'frontend'
    description: >
      ...
  - type: "fix"
    path: 'backend'
    description: >
      ...
    cwes:
      - "CWE-22"  # CWE-22: Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')
  - type: "false_positive"
    path: 'backend'
    description: >
       ....
    cwes:
      - "CWE-20"  # CWE-20: Improper Input Validation
  - type: "false_positive"
    path: "frontend"
    description: >
      ...
    cwes:
      - "CWE-79"  # CWE-79: Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')

1

On the PolicyIQ page, you will see five policies generated.

2

You can view all the different policies with their respective paths.