> ## 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.

# Basic Scanning

> Learn the fundamentals of scanning code with KafkaCode

## Basic Usage

The most common way to use KafkaCode is with the `scan` command:

```bash theme={null}
kafkacode scan <directory>
```

## Scanning Your Project

<Tabs>
  <Tab title="Current Directory">
    Scan the current directory and all subdirectories:

    ```bash theme={null}
    kafkacode scan .
    ```
  </Tab>

  <Tab title="Specific Directory">
    Scan a specific project folder:

    ```bash theme={null}
    kafkacode scan /path/to/your/project
    ```

    Or using relative paths:

    ```bash theme={null}
    kafkacode scan ./src
    kafkacode scan ../backend
    ```
  </Tab>

  <Tab title="With npx">
    Run without installing globally:

    ```bash theme={null}
    npx kafkacode scan ./src
    ```
  </Tab>
</Tabs>

## Understanding the Output

### Scan Summary

Every scan starts with a summary section:

```bash theme={null}
🎯 PRIVACY SCAN REPORT
═══════════════════════════════════════════════════════════

📊 SCAN SUMMARY
📁 Directory: ./src
⏰ Timestamp: 2025-01-15 10:30:45
📄 Files Scanned: 25
🔍 Total Issues: 3
🏆 Privacy Grade: 🟡 B-

═══════════════════════════════════════════════════════════
```

**Key Metrics:**

* **Directory**: Path that was scanned
* **Timestamp**: When the scan was performed
* **Files Scanned**: Number of source files analyzed
* **Total Issues**: Count of all findings
* **Privacy Grade**: Overall grade (A+ to F)

### Issue Listings

Issues are grouped by severity:

```bash theme={null}
🔴 CRITICAL (1)
────────────────────────────────────────────────────────────
  📄 src/config.js:12
     AWS Access Key detected
     aws_access_key_id = "AKIAIOSFODNN7EXAMPLE"

     💡 Recommendation: Move to environment variables

🟠 HIGH (1)
────────────────────────────────────────────────────────────
  📄 src/auth.js:23
     API key found in code
     const apiKey = "sk_live_abc123..."

     💡 Recommendation: Use configuration management

🟡 MEDIUM (2)
────────────────────────────────────────────────────────────
  📄 src/utils/validator.js:45
     Email address found in code
     const adminEmail = "admin@company.com"

     💡 Recommendation: Use configuration file

  📄 src/database/connection.js:8
     Potential database connection string
     const dbUrl = "mongodb://localhost:27017/mydb"

     💡 Recommendation: Use environment variables

🔵 LOW (3)
────────────────────────────────────────────────────────────
  📄 src/config.js:5
     IP address detected
     const serverIP = "192.168.1.100"

     💡 Recommendation: Use DNS names when possible
```

**Each finding includes:**

* **File path**: Location of the issue
* **Line number**: Exact line where issue was found
* **Description**: What was detected
* **Code snippet**: The problematic code
* **Recommendation**: How to fix it

## Verbose Mode

Get detailed progress information during scanning:

```bash theme={null}
kafkacode scan ./src --verbose
```

**Verbose output shows:**

```bash theme={null}
🚀 Starting KafkaCode privacy scan...
📁 Discovering source code files...
Found 25 files to analyze
🔍 Performing privacy analysis...

Analyzing: src/config.js
Analyzing: src/auth.js
Analyzing: src/utils/validator.js
Analyzing: src/database/connection.js
...

✅ Analysis complete
```

<Info>
  Verbose mode is helpful for:

  * Understanding what KafkaCode is doing
  * Debugging issues
  * Monitoring progress on large codebases
</Info>

## Exit Codes

KafkaCode uses exit codes to indicate results:

| Exit Code | Meaning                       |
| --------- | ----------------------------- |
| `0`       | ✅ No issues found             |
| `1`       | ⚠️ Issues found or scan error |

**Use in scripts:**

```bash theme={null}
# Exit if issues found
kafkacode scan ./src || exit 1

# Or with custom handling
if kafkacode scan ./src; then
  echo "✅ No privacy issues detected"
else
  echo "⚠️ Privacy issues found, see report above"
  exit 1
fi
```

## Common Scenarios

### Scenario 1: Quick Project Check

```bash theme={null}
# Navigate to project
cd ~/projects/my-app

# Quick scan
kafkacode scan .
```

### Scenario 2: Scan Before Commit

```bash theme={null}
# Scan staged changes
git diff --name-only --cached | xargs -I {} dirname {} | sort -u | xargs kafkacode scan

# Or scan entire src directory
kafkacode scan ./src
```

### Scenario 3: Focus on Specific Directory

```bash theme={null}
# Scan only backend code
kafkacode scan ./backend

# Scan only specific module
kafkacode scan ./src/auth
```

### Scenario 4: Multiple Directory Scan

```bash theme={null}
# Scan multiple directories (requires loop)
for dir in frontend backend mobile; do
  echo "Scanning $dir..."
  kafkacode scan ./$dir
done
```

## What Files Are Scanned?

### Included Files

KafkaCode automatically scans these file types:

<CardGroup cols={2}>
  <Card title="Python" icon="python">
    `*.py`
  </Card>

  <Card title="JavaScript" icon="js">
    `*.js`, `*.jsx`
  </Card>

  <Card title="TypeScript" icon="code">
    `*.ts`, `*.tsx`
  </Card>

  <Card title="Java" icon="java">
    `*.java`
  </Card>

  <Card title="Go" icon="golang">
    `*.go`
  </Card>

  <Card title="Ruby" icon="gem">
    `*.rb`
  </Card>

  <Card title="PHP" icon="php">
    `*.php`
  </Card>
</CardGroup>

### Excluded Files & Directories

Automatically skipped:

**Version Control:**

* `.git/`
* `.svn/`
* `.hg/`

**Dependencies:**

* `node_modules/`
* `vendor/`
* `bower_components/`

**Python Virtual Environments:**

* `venv/`
* `.venv/`
* `env/`
* `__pycache__/`
* `.pytest_cache/`
* `.mypy_cache/`

**Build Outputs:**

* `build/`
* `dist/`
* `target/`
* `out/`
* `.next/`
* `.nuxt/`

**Test Coverage:**

* `coverage/`
* `.coverage/`

**Plus any files/directories in your `.gitignore`**

## Gitignore Support

KafkaCode automatically respects your `.gitignore` file:

```gitignore theme={null}
# .gitignore
*.env
*.key
*.pem
secrets/
config/local.*
credentials.json
```

All matching files will be excluded from scanning.

<Tip>
  **Pro Tip**: If you want KafkaCode to skip certain files, add them to your `.gitignore`. This is especially useful for test fixtures or mock data.
</Tip>

## Performance Tips

<AccordionGroup>
  <Accordion icon="folder" title="Scan Specific Directories">
    Instead of scanning the entire project, target specific directories:

    ```bash theme={null}
    # Instead of this:
    kafkacode scan .

    # Do this:
    kafkacode scan ./src ./lib
    ```
  </Accordion>

  <Accordion icon="filter" title="Use .gitignore Effectively">
    Add large directories to `.gitignore`:

    ```gitignore theme={null}
    # Exclude test fixtures
    tests/fixtures/

    # Exclude generated files
    generated/

    # Exclude third-party code
    third_party/
    ```
  </Accordion>

  <Accordion icon="gauge" title="Monitor Scan Time">
    Use `time` to measure performance:

    ```bash theme={null}
    time kafkacode scan ./src
    ```

    Typical performance:

    * Small project (\< 100 files): 2-5 seconds
    * Medium project (100-1000 files): 10-30 seconds
    * Large project (> 1000 files): 30-120 seconds
  </Accordion>
</AccordionGroup>

## Interpreting Results

### No Issues Found

```bash theme={null}
📊 SCAN SUMMARY
📄 Files Scanned: 25
🔍 Total Issues: 0
🏆 Privacy Grade: 🟢 A+

✅ No privacy issues detected!
```

**Action:** Great! Your code is clean. Continue following best practices.

### Minor Issues Found

```bash theme={null}
📊 SCAN SUMMARY
📄 Files Scanned: 25
🔍 Total Issues: 3
🏆 Privacy Grade: 🟢 A-

🔵 LOW (3)
  📄 src/config.js:5
     IP address detected
```

**Action:** Review and address minor issues when convenient.

### Critical Issues Found

```bash theme={null}
📊 SCAN SUMMARY
📄 Files Scanned: 25
🔍 Total Issues: 5
🏆 Privacy Grade: 🔴 D

🔴 CRITICAL (2)
  📄 src/config.js:12
     AWS Access Key detected

  📄 src/stripe.js:8
     Stripe Secret Key detected
```

**Action:** Fix critical issues immediately before deploying!

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Options" icon="terminal" href="/usage/cli-options">
    Explore all command-line options
  </Card>

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

  <Card title="CI/CD Integration" icon="code-branch" href="/usage/ci-cd-integration">
    Automate scanning in your pipeline
  </Card>

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

<Warning>
  **Important**: KafkaCode is a static analysis tool. It may produce false positives or miss certain issues. Always review findings in context and use it as part of a comprehensive security strategy.
</Warning>