# Django Access Inspector

Django Access Inspector is a comprehensive access control app for Django that helps you enforce fine-grained access control on your views. It provides a flexible and easy-to-use interface to check and analyze authentication and permission classes for each view in your Django project.

## Installation

To install Django Access Inspector, you can use `pip`, `poetry`, or `uv`. Here are the commands:

```shell
pip install django-access-inspector
```

```shell
poetry add django-access-inspector
```

```shell
uv add django-access-inspector
```

After installing, make sure to add `"django_access_inspector"` to your `INSTALLED_APPS` setting in your Django project's `settings.py` file:

```python
INSTALLED_APPS = [
    ...,
    "django_access_inspector",
]
```

## Usage

### Basic Usage

To run Django Access Inspector, use the following command:

```shell
python manage.py inspect_access_control
```

By default, it will provide a human-readable output. If you prefer a JSON output, you can use the `--output json` flag:

```shell
python manage.py inspect_access_control --output json
```

### CI Mode

Django Access Inspector supports a CI mode that helps ensure your application's access control remains secure over time. This mode uses snapshots to track the current state of your endpoints and fails if new unauthenticated or unchecked endpoints are introduced.

#### Generating a Snapshot

First, generate a baseline snapshot of your current access control state:

```shell
python manage.py inspect_access_control --snapshot baseline.json
```

This will save the current state of all your endpoints to a JSON file.

#### Running in CI Mode

In your CI pipeline, use the snapshot to validate that no new security issues have been introduced:

```shell
python manage.py inspect_access_control --ci --snapshot baseline.json
```

The command will:
- Compare the current analysis with the saved snapshot
- Exit with code 0 if no new security issues are found
- Exit with code 1 if new unauthenticated or unchecked endpoints are detected
- Display detailed information about any changes found

This is particularly useful in CI/CD pipelines to prevent introducing new security vulnerabilities.

### Debug Mode

When you need to troubleshoot authentication detection issues, you can enable detailed debug logging:

```shell
python manage.py inspect_access_control --debug
```

Debug mode provides detailed information about:
- URL pattern extraction process
- View function discovery and analysis
- Authentication and permission detection logic
- Categorization decisions for each endpoint
- Detailed analysis of Django and DRF authentication mechanisms

This helps you understand why certain endpoints might be categorized as "unchecked" and allows you to verify that the tool correctly identifies your authentication setup.

## Example

![cli example output](/assets/cli_output.png)

Here's an interpretation of the output:

- **Unchecked views**: Views that Django Access Inspector was not able to check. As the tool is still a work in progress, we aim to make it check all views in the future.
- **Model Admin views**: Views generated by Django Admin that are checked with the Django Admin permission system.
- **Views**: All views that Django Access Inspector was able to check, including their authentication and permission classes.

## MCP Server (LLM Integration)

Django Access Inspector ships with a Model Context Protocol (MCP) server so LLM tools and editors can call the inspector programmatically. The server runs over STDIO and exposes a tool and a prompt designed for security reviews of your endpoints.

### Start the server

Run the Django management command from your project:

```shell
python manage.py start_mcp_server
```

Enable debug logging:

```shell
python manage.py start_mcp_server --debug
```

If you prefer `uv`:

```shell
uv run manage.py start_mcp_server
```

Convenience targets (if using this repo):

```shell
make start_mcp      # starts the MCP server
make inspector      # opens the MCP Inspector UI
```

### Try it with MCP Inspector

You can explore the server using the official MCP Inspector:

```shell
npx @modelcontextprotocol/inspector
```

In the Inspector, choose to launch a server and enter the command you use locally, for example `python manage.py start_mcp_server` (or `uv run manage.py start_mcp_server`). The Inspector will connect over STDIO and list the available tools and prompts.

### Exposed tools and prompts

The server exposes one tool and one prompt:

- `analyze_endpoints(endpoint: str = "", snapshot_path: str = "")`
  - Analyze all endpoints (no args) or a single endpoint by name.
  - When `snapshot_path` is provided, returns only CI‑failing changes compared to the snapshot (new unauthenticated or new unchecked endpoints).
  - Returns structured JSON with a `summary` and endpoint lists.

- `security_analysis_prompt(endpoint_name: str = "", snapshot_path: str = "")`
  - Generates a ready‑to‑use Markdown prompt to guide an LLM through a security assessment workflow for your endpoints.

### Notes

- Transport is STDIO; no network port is opened.
- The server relies on your Django project settings (same as other management commands). Ensure your environment can import your project and `INSTALLED_APPS` includes `"django_access_inspector"`.
- The MCP integration uses `fastmcp` under the hood and is included as a dependency.
