> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kafkalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detection Methods

> Learn how KafkaCode identifies privacy and compliance issues

## Overview

KafkaCode uses multiple detection methods to identify privacy issues, secrets, and compliance violations in your source code.

## Detection Categories

<CardGroup cols={2}>
  <Card title="Secrets Detection" icon="key" color="#dc2626">
    API keys, tokens, credentials
  </Card>

  <Card title="PII Detection" icon="user-shield" color="#ea580c">
    Personal identifiable information
  </Card>

  <Card title="Compliance Checks" icon="certificate" color="#eab308">
    GDPR, CCPA requirements
  </Card>

  <Card title="Context Analysis" icon="brain" color="#3b82f6">
    AI-powered semantic analysis
  </Card>
</CardGroup>

## Secrets Detection

### Critical Level Secrets

<AccordionGroup>
  <Accordion icon="aws" title="AWS Access Keys">
    **Pattern:** `AKIA[0-9A-Z]{16}`

    **Example:**

    ```python theme={null}
    # ❌ Bad: Hardcoded AWS key
    aws_access_key = "AKIAIOSFODNN7EXAMPLE"

    # ✅ Good: Use environment variables
    aws_access_key = os.getenv('AWS_ACCESS_KEY_ID')
    ```

    **Severity:** Critical (100 points)
  </Accordion>

  <Accordion icon="key" title="Private Keys">
    **Pattern:** `-----BEGIN (RSA |EC )?PRIVATE KEY-----`

    **Example:**

    ```javascript theme={null}
    // ❌ Bad: Embedded private key
    const privateKey = `-----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEA...
    -----END RSA PRIVATE KEY-----`;

    // ✅ Good: Load from secure file
    const privateKey = fs.readFileSync('/secure/path/key.pem');
    ```

    **Severity:** Critical (100 points)
  </Accordion>

  <Accordion icon="credit-card" title="Stripe API Keys">
    **Pattern:** `sk_live_[0-9a-zA-Z]{24}`

    **Example:**

    ```javascript theme={null}
    // ❌ Bad: Hardcoded Stripe key
    const stripe = require('stripe')('sk_live_51H...');

    // ✅ Good: Use environment variable
    const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
    ```

    **Severity:** Critical (100 points)
  </Accordion>

  <Accordion icon="database" title="Database Credentials">
    **Pattern:** Password/credentials in connection strings

    **Example:**

    ```python theme={null}
    # ❌ Bad: Hardcoded database password
    DATABASE_URL = "postgresql://user:password123@localhost/db"

    # ✅ Good: Use environment variables
    DATABASE_URL = os.getenv('DATABASE_URL')
    ```

    **Severity:** Critical (100 points)
  </Accordion>
</AccordionGroup>

### High Level Secrets

<AccordionGroup>
  <Accordion icon="github" title="OAuth Tokens">
    **Pattern:** GitHub, GitLab, and other OAuth tokens

    **Example:**

    ```javascript theme={null}
    // ❌ Bad: Hardcoded OAuth token
    const token = 'ghp_1234567890abcdef';

    // ✅ Good: Use secure storage
    const token = await getSecureToken();
    ```

    **Severity:** High (50 points)
  </Accordion>

  <Accordion icon="lock" title="JWT Secrets">
    **Pattern:** `jwt_secret`, `JWT_SECRET` assignments

    **Example:**

    ```python theme={null}
    # ❌ Bad: Hardcoded JWT secret
    JWT_SECRET = "mysecretkey123"

    # ✅ Good: Use environment variable
    JWT_SECRET = os.getenv('JWT_SECRET')
    ```

    **Severity:** High (50 points)
  </Accordion>

  <Accordion icon="plug" title="API Keys">
    **Pattern:** Generic API key patterns

    **Example:**

    ```javascript theme={null}
    // ❌ Bad: Hardcoded API key
    const apiKey = 'api_key_1234567890abcdef';

    // ✅ Good: Load from config
    const apiKey = config.get('API_KEY');
    ```

    **Severity:** High (50 points)
  </Accordion>
</AccordionGroup>

## PII Detection

### Medium Level PII

<AccordionGroup>
  <Accordion icon="envelope" title="Email Addresses">
    **Pattern:** `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}`

    **Example:**

    ```javascript theme={null}
    // ❌ Bad: Hardcoded email
    const adminEmail = "admin@company.com";

    // ✅ Good: Use configuration
    const adminEmail = config.get('ADMIN_EMAIL');
    ```

    **Severity:** Medium (10 points)

    **GDPR Consideration:** Email addresses are PII under GDPR
  </Accordion>

  <Accordion icon="phone" title="Phone Numbers">
    **Pattern:** Various international formats

    **Example:**

    ```python theme={null}
    # ❌ Bad: Hardcoded phone number
    support_phone = "+1-555-123-4567"

    # ✅ Good: Use configuration
    support_phone = config.SUPPORT_PHONE
    ```

    **Severity:** Medium (10 points)

    **CCPA Consideration:** Phone numbers are personal information
  </Accordion>

  <Accordion icon="fingerprint" title="Social Security Numbers">
    **Pattern:** `\d{3}-\d{2}-\d{4}`

    **Example:**

    ```javascript theme={null}
    // ❌ Bad: SSN in code
    const testSSN = "123-45-6789";

    // ✅ Good: Use mock data service
    const testSSN = mockDataService.generateFakeSSN();
    ```

    **Severity:** Critical (100 points)
  </Accordion>

  <Accordion icon="id-card" title="Credit Card Numbers">
    **Pattern:** Luhn algorithm validated sequences

    **Example:**

    ```python theme={null}
    # ❌ Bad: Test credit card in code
    test_card = "4111111111111111"

    # ✅ Good: Use test mode tokens
    test_card = stripe.Token.create_test_card()
    ```

    **Severity:** Critical (100 points)
  </Accordion>
</AccordionGroup>

### Low Level PII

<AccordionGroup>
  <Accordion icon="network-wired" title="IP Addresses">
    **Pattern:** `\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b`

    **Example:**

    ```javascript theme={null}
    // ⚠️ Review: IP address in code
    const serverIP = "192.168.1.100";

    // ✅ Better: Use DNS names
    const serverHost = "api.company.com";
    ```

    **Severity:** Low (1 point)
  </Accordion>

  <Accordion icon="link" title="URLs with Sensitive Paths">
    **Pattern:** URLs containing `/api/`, `/admin/`, `/secret/`

    **Example:**

    ```python theme={null}
    # ⚠️ Review: Sensitive URL in code
    admin_url = "https://api.company.com/admin/users"

    # ✅ Better: Use route constants
    admin_url = f"{BASE_URL}/{ADMIN_ROUTES.users}"
    ```

    **Severity:** Low (1 point)
  </Accordion>
</AccordionGroup>

## High Entropy Strings

KafkaCode detects strings with high randomness that might be secrets:

```javascript theme={null}
// Calculate entropy
function calculateEntropy(str) {
  const freq = {};
  for (let c of str) {
    freq[c] = (freq[c] || 0) + 1;
  }

  let entropy = 0;
  for (let c in freq) {
    const p = freq[c] / str.length;
    entropy -= p * Math.log2(p);
  }

  return entropy;
}
```

**Thresholds:**

* Entropy > 4.5 and length > 16: Potential secret
* Entropy > 5.0 and length > 24: Likely secret

**Example:**

```python theme={null}
# High entropy string detected
secret = "x7K9mP2nQ8vL4wR6tY3zA1bC5dE0fG"  # Entropy: 4.8

# Lower entropy, likely not a secret
message = "hello world welcome back"  # Entropy: 3.2
```

## Sensitive Keywords

Detection of sensitive data based on variable naming:

<Tabs>
  <Tab title="Critical Keywords">
    ```javascript theme={null}
    // These trigger CRITICAL alerts
    const password = "secret123";
    const privateKey = "...";
    const secret = "...";
    const token = "...";
    const credential = "...";
    ```
  </Tab>

  <Tab title="High Keywords">
    ```javascript theme={null}
    // These trigger HIGH alerts
    const apiKey = "...";
    const authToken = "...";
    const accessToken = "...";
    const sessionSecret = "...";
    ```
  </Tab>

  <Tab title="Medium Keywords">
    ```javascript theme={null}
    // These trigger MEDIUM alerts
    const email = "user@example.com";
    const phoneNumber = "+1234567890";
    const ssn = "123-45-6789";
    ```
  </Tab>
</Tabs>

## Context-Aware Detection

The AI analyzer understands code context:

### Example 1: Configuration vs Hardcoded

```javascript theme={null}
// ✅ Good: Configuration object
const config = {
  email: process.env.ADMIN_EMAIL,
  apiKey: process.env.API_KEY
};

// ❌ Bad: Hardcoded values
const config = {
  email: "admin@company.com",
  apiKey: "1234567890abcdef"
};
```

The AI recognizes that hardcoded values are problematic while env vars are acceptable.

### Example 2: Test Data vs Real Data

```python theme={null}
# ✅ Good: Clearly marked test data
TEST_EMAIL = "test@example.com"

# ❌ Bad: Looks like real data
admin_email = "john.doe@company.com"
```

The AI understands context and reduces false positives for test data.

### Example 3: Public vs Private

```javascript theme={null}
// ✅ Public info is okay
const publicKey = "-----BEGIN PUBLIC KEY-----...";

// ❌ Private key is critical
const privateKey = "-----BEGIN PRIVATE KEY-----...";
```

## Compliance-Specific Detection

### GDPR Compliance

<CardGroup cols={2}>
  <Card title="Personal Data" icon="user">
    * Name, email, phone
    * IP addresses
    * Location data
    * Cookies with PII
  </Card>

  <Card title="Special Categories" icon="shield-halved">
    * Health data
    * Biometric data
    * Genetic data
    * Religious/political views
  </Card>
</CardGroup>

### CCPA Compliance

<CardGroup cols={2}>
  <Card title="Personal Information" icon="address-card">
    * Contact information
    * Financial information
    * Purchase history
    * Browsing history
  </Card>

  <Card title="Identifiers" icon="fingerprint">
    * Device IDs
    * IP addresses
    * Cookie IDs
    * Account usernames
  </Card>
</CardGroup>

## False Positive Reduction

KafkaCode uses several techniques to reduce false positives:

<Steps>
  <Step title="Context Analysis">
    AI understands if a value is a placeholder, test data, or real credential
  </Step>

  <Step title="Assignment Context">
    Only flags sensitive keywords when they're being assigned values
  </Step>

  <Step title="Environment Variable Detection">
    Recognizes when values come from env vars or config files
  </Step>

  <Step title="Comment Analysis">
    Understands `# TODO` or `# FIXME` comments that mention sensitive data
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion icon="check" title="Do's">
    * ✅ Use environment variables for all secrets
    * ✅ Store credentials in secure vaults (AWS Secrets Manager, etc.)
    * ✅ Use `.env` files with `.gitignore`
    * ✅ Rotate secrets regularly
    * ✅ Use different secrets for dev/staging/prod
  </Accordion>

  <Accordion icon="xmark" title="Don'ts">
    * ❌ Never commit secrets to version control
    * ❌ Don't hardcode API keys or passwords
    * ❌ Don't store PII unnecessarily
    * ❌ Don't log sensitive information
    * ❌ Don't share secrets in plain text
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Privacy Grading" icon="chart-line" href="/concepts/privacy-grading">
    Understand how grades are calculated
  </Card>

  <Card title="Interpreting Results" icon="magnifying-glass-chart" href="/usage/interpreting-results">
    Learn to read scan reports
  </Card>

  <Card title="Custom Patterns" icon="wrench" href="/advanced/custom-patterns">
    Add your own detection rules
  </Card>

  <Card title="Examples" icon="book" href="/examples/basic-scan">
    See real-world examples
  </Card>
</CardGroup>