Metadata-Version: 2.4
Name: saferevoke
Version: 0.1.0a1
Summary: Experimental permission-removal testing for Python applications
License-Expression: MIT
Project-URL: Repository, https://github.com/rishisugavanam2024-beep/disign-usability-security-
Project-URL: Documentation, https://github.com/rishisugavanam2024-beep/disign-usability-security-/blob/main/docs/pytest-integration.md
Project-URL: Issues, https://github.com/rishisugavanam2024-beep/disign-usability-security-/issues
Keywords: django,pytest,permissions,authorization,security,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: pytest
Requires-Dist: pytest<10,>=8; extra == "pytest"
Requires-Dist: pytest-django<5,>=4.8; extra == "pytest"
Requires-Dist: Django<5.3,>=5.2; extra == "pytest"
Provides-Extra: web
Requires-Dist: Flask==3.1.2; extra == "web"
Dynamic: license-file

# SafeRevoke

**Experimental permission-removal testing for Python and Django applications.**

SafeRevoke helps developers investigate what changes when an access grant is
removed. Its pytest plugin reuses existing Django test fixtures and assertions,
records actual authorization decisions, and generates HTML/JSON findings.

Version **0.1.0a1** is an early alpha. Support currently covers serial, synchronous
pytest-django tests using Django 5.2's standard user/group authorization backend.
Licensed under the MIT License.

## Install

After the release is available on PyPI:

```shell
python -m pip install --pre "saferevoke[pytest]"
```

For development from the repository:

```shell
python -m pip install -e ".[pytest]"
```

The plugin registers automatically. Permission mutation is disabled until
`--saferevoke` is supplied; installing it does not enable mutation in ordinary tests.

## Use your existing Django tests

```shell
python -m pytest tests/test_refunds.py --ds=myproject.test_settings --saferevoke --saferevoke-deny group:refund_operators:orders.approve_refund
```

Replace the illustrative test path, Django settings and permission selector with
values from your application. Fixtures must create the relevant test users and
grants. Test functions do not need SafeRevoke workflow wrappers.

Selectors use `user:USERNAME:app_label.codename` for a direct grant or
`group:GROUP_NAME:app_label.codename` for a group grant. Repeat
`--saferevoke-deny` to test additional grants independently.

To use observed dependencies to skip unrelated mutation variants before fixture
setup, add:

```shell
--saferevoke-selection affected
```

Every selected test still gets a fresh baseline. Empty or uncertain traces keep
their mutation runs. Full mode, `--saferevoke-selection all`, is the default.

## Results

Reports are written to `reports/pytest-saferevoke/report.html` and `report.json`.
They include baselines, permission traces, remaining-access findings, failed
assertions and selection counts. Tests that fail under permission removal retain
pytest's usual failure status and nonzero exit code. This may indicate expected
access enforcement or a broken required workflow; review the evidence.

The engine can also compare observed identities and privilege scope to flag a
more privileged fallback. Such a path must actually execute and reach the
supported permission backend to be detected. Passing tests alone are not proof
that production permission removal is safe.

## Boundaries

- Runs against the test database managed by pytest-django, with database rollback
  after each observed test body.
- Supports standard Django direct/group permissions and active non-superuser
  identities. Custom authorization backends, async/live-server workflows, xdist
  and multiple database aliases are not supported by this alpha.
- Database rollback does not reset files, email, workers or external services.
  Use isolated test settings and deterministic fixtures.
- Dependency selection covers observed baseline paths. Direct permission-table
  queries, custom checks and unobserved branches can be missed. Full mode remains
  available for broader validation.
- The library does not automatically sandbox or copy an entire application.

## Documentation and examples

- [Installation, runnable example and compatibility](https://github.com/rishisugavanam2024-beep/disign-usability-security-/blob/main/docs/pytest-integration.md)
- [Django adapter](https://github.com/rishisugavanam2024-beep/disign-usability-security-/blob/main/docs/django-integration.md)
- [Source and issue tracker](https://github.com/rishisugavanam2024-beep/disign-usability-security-)
