{"id":39935442,"url":"https://github.com/peerigon/access-control-testing","last_synced_at":"2026-01-18T18:34:42.672Z","repository":{"id":283333608,"uuid":"874780199","full_name":"peerigon/access-control-testing","owner":"peerigon","description":"Automated detection of Broken Access Control vulnerabilities based on enhanced OpenAPI specifications","archived":false,"fork":false,"pushed_at":"2025-03-19T17:08:23.000Z","size":667,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-19T18:24:50.680Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peerigon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-18T12:57:05.000Z","updated_at":"2025-03-19T17:08:28.000Z","dependencies_parsed_at":"2025-03-20T02:33:26.270Z","dependency_job_id":null,"html_url":"https://github.com/peerigon/access-control-testing","commit_stats":null,"previous_names":["peerigon/access-control-testing"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/peerigon/access-control-testing","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peerigon%2Faccess-control-testing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peerigon%2Faccess-control-testing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peerigon%2Faccess-control-testing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peerigon%2Faccess-control-testing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peerigon","download_url":"https://codeload.github.com/peerigon/access-control-testing/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peerigon%2Faccess-control-testing/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28547292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T14:59:57.589Z","status":"ssl_error","status_checked_at":"2026-01-18T14:59:46.540Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T18:34:42.611Z","updated_at":"2026-01-18T18:34:42.665Z","avatar_url":"https://github.com/peerigon.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eAccess Control Testing Tool\u003c/h1\u003e\n  \u003cp align=\"center\"\u003eAutomated detection of Broken Access Control vulnerabilities based on enhanced OpenAPI specifications\u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Introduction\n\nThis tool automates testing web applications for \u003ca href=\"https://owasp.org/Top10/A01_2021-Broken_Access_Control/\"\u003eBroken Access Control\u003c/a\u003e vulnerabilities, with a particular focus on detecting \u003ca href=\"https://owasp.org/API-Security/editions/2023/en/0xa1-broken-object-level-authorization/\"\u003eBroken Object Level Authorization (BOLA)\u003c/a\u003e. Broken Access Control is ranked **#1 in the OWASP Top 10 (2021)**, while BOLA is ranked **#1 in the OWASP API Security Top 10 (2023)**, highlighting the importance of effective access control mechanisms in modern web applications.\n\nDeveloped by [Peerigon](https://peerigon.com/) as part of a bachelor's thesis, it leverages a specially annotated OpenAPI specification to explicitly determine which resources an API endpoint accesses and the type of access involved. For details on annotations, see [Annotating Resources](#2-annotating-resources).\n\nThe tool generates test cases based on defined user-resource relationships and [executes them through a test runner](#running-tests), sending requests to the application and verifying whether each request was permitted or denied. The outcome is then compared to the expected behavior defined through a policy replication, enabled by [user-resource relationship definitions](#4-defining-users-and-resources). Results are displayed in a console-based report.\n\n---\n\n## Installation\n\nSince the tool is not yet published on npm, installation is done using [yalc](https://github.com/wclr/yalc).\n\nInstall `yalc` globally first:\n\n```bash\nnpm install -g yalc\n```\n\nClone this repository, navigate to the directory, and run:\n\n```bash\nnpm install\nnpm run publish:local\n```\n\nThen, inside your project's directory, add the tool:\n\n```bash\nnpx yalc add access-control-testing\nnpm install\n```\n\n---\n\n## Limitations\n\nAdditional security mechanisms like **CSRF tokens**, **rate limiting**, or **IP blocking** should be disabled during testing. Otherwise, they may interfere with the testing process. For example, a `403 Forbidden` status code caused by IP blocking might be misinterpreted by the tool. Temporarily disable such protections via environment variables or similar mechanisms to ensure accurate test results.\n\nCurrently, only one resource per operation can be defined. The tool does not support multiple resources in a single route (e.g., `/groups/:groupId/members/:memberId`). Simple routes like `/members/:memberId` are fully supported.\n\nThe tool only supports APIs communicating via JSON. XML or other formats are not yet supported.\n\nCombining multiple Security Schemes for authentication is not supported. While OpenAPI allows defining multiple Security Schemes with an OR-relationship, the tool always selects only the first defined Security Scheme and does not use others as fallback.\n\n---\n\n## Assumptions\n\nThe tool assumes tested web applications follow this sequence when handling requests:\n\n1. User identity verification (_Authentication_)\n2. User permission verification (_Authorization_)\n3. Request syntax and semantic validation\n\nIf this order is not maintained, the tool may produce inaccurate test outcomes.\n\nThe tested web application should return semantically correct status codes, as the tool determines whether a test has failed or passed based on the returned status code. The status code `403 Forbidden` should only be sent when an authorization check concludes that the requested resource is not accessible to the user making the request. `403` should not be used for violations of business logic (e.g., when a request is semantically or syntactically incorrect or when the requested action is not possible in the current state of the resource).\n\n---\n\n## Setup\n\n### 1. Provide OpenAPI Specification\n\nMake your application's OpenAPI specification available through your web server in either JSON or YAML format.\n\n\u003e [!IMPORTANT]  \n\u003e Local file paths are not allowed for security reasons. Instead, you must use a URL that starts with `http://` or `https://`.\n\n---\n\n### 2. Annotating Resources\n\nFirst, determine clearly which API routes represent resources and the type of access (`create`, `read`, `update`, `delete`) they involve.\n\nThe following custom annotations (prefixed with `x-act-`) are required to specify resources and access types:\n\n- `x-act-resource-name`: Indicates the resource accessed.\n- `x-act-resource-access`: Specifies access type.\n\nAnnotations can be inline or nested under `x-act`:\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eExample of Inline Annotation\u003c/strong\u003e\u003c/summary\u003e\n\n```yaml\nx-act-resource-name: Todo\nx-act-resource-access: read\n```\n\n\u003c/details\u003e\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eExample of Nested Annotation\u003c/strong\u003e\u003c/summary\u003e\n\n```yaml\nx-act:\n  resource-name: Todo\n  resource-access: read\n```\n\n\u003c/details\u003e\n\nAnnotations for resources can be placed in path parameters, query parameters, or the request body.\nAdditionally, they can be defined at the operation level, which is particularly relevant for create operations where no identifier is available for annotation.\n\nAdditionally, they can be defined at the operation level for operations that do not include a resource parameter but still perform an action on a resource. This includes, for example, creating (`create`) a new resource or reading (`read`) resources without specifying an identifier (i.e., accessing all resources).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eComplete Example of OpenAPI Annotations\u003c/strong\u003e\u003c/summary\u003e\n\n```yaml\npaths:\n  /todos:\n    get:\n      # ...\n      x-act:\n        resource-name: Todo\n        resource-access: read\n    post:\n      # ...\n      x-act:\n        resource-name: Todo\n        resource-access: create\n\n  /todos/{id}:\n    # ...\n    get:\n      parameters:\n        - name: id\n          in: path\n          required: true\n          schema:\n            type: string\n          x-act:\n            resource-name: Todo\n            resource-access: read\n```\n\n\u003c/details\u003e\n\n---\n\n### 3. Annotating Authentication Endpoints\n\nBefore annotating authentication endpoints, ensure a valid security scheme is defined in your OpenAPI specification. See the [Security Scheme documentation](https://learn.openapis.org/specification/security.html).\n\n\u003e [!WARNING]  \n\u003e The tool does not support combining multiple Security Schemes for authentication. If an operation or the entire API requires multiple Security Schemes to be used together for authentication, this will not work. While OpenAPI allows defining multiple Security Schemes as an OR-relationship, the tool always selects only the first defined Security Scheme and does not use others as fallback.\n\nUse these annotations to allow the tool to authenticate automatically:\n\n- `x-act-auth-endpoint`: Must match your defined security scheme key and must be provided on operation-level.\n- `x-act-auth-field`: Defines the relevant fields for authentication and must be set to one of the following valid types:\n\n  | Type         | Description                                                                                          |\n  | ------------ | ---------------------------------------------------------------------------------------------------- |\n  | `identifier` | Specifies the field in the request body that contains the user identifier (e.g., username or email). |\n  | `password`   | Defines the field in the request body that holds the user's password.                                |\n  | `token`      | Specifies the field in the response body where the authentication token is returned.                 |\n\nEach value must be explicitly defined either as `x-act-auth-field-type` directly or as follows:\n\n```yaml\nx-act-auth-field:\n  type: identifier | password | token\n```\n\n\u003e [!WARNING]  \n\u003e For bearer authentication, the token field must be at the top level of the response.  \n\u003e Nested fields like `{ data: { token: \"\u003ctoken\u003e\" } }` are currently not supported.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eExample of an Authentication Endpoint (Bearer)\u003c/strong\u003e\u003c/summary\u003e\n\n```yaml\npaths:\n  /login/bearer:\n    post:\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              type: object\n              properties:\n                username:\n                  type: string\n                  x-act-auth-field:\n                    type: identifier\n                password:\n                  type: string\n                  x-act-auth-field:\n                    type: password\n      responses:\n        \"200\":\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  token:\n                    type: string\n                    x-act-auth-field:\n                      type: token\n      x-act-auth-endpoint: bearerHttpAuthentication\n```\n\n\u003c/details\u003e\n\n---\n\n### 4. Defining Users and Resources\n\nDefine user-resource relationships explicitly. Resource names must match exactly (case-sensitive) the values used in the OpenAPI annotations (`x-act-resource-name`):\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eExample of User-Resource Definition\u003c/strong\u003e\u003c/summary\u003e\n\n```typescript\nimport { Resource, User } from \"access-control-testing\";\n\nconst user1 = new User(\"myusername\", \"mysecretpassword\");\nconst todoResource = new Resource(\"Todo\"); // Name must exactly match OpenAPI spec annotation\n\nuser1.canView(todoResource, 123); // user1 can view Todo instance with identifier 123\nuser1.canEdit(todoResource, 123); // user1 can edit Todo instance with identifier 123\nuser1.canDelete(todoResource, 123); // user1 can delete Todo instance with identifier 123\nuser1.canCreate(todoResource); // user1 can create new Todo instances\nuser1.owns(todoResource); // user1 owns created Todo instances\n```\n\n\u003c/details\u003e\n\n---\n\n### 5. Configuration Options\n\nProvide the following properties when configuring the tool:\n\n- `apiBaseUrl`: The base URL where your API is accessible. It must be present in the `servers` array of the OpenAPI spec.\n- `openApiUrl`: URL pointing to your annotated OpenAPI spec.\n- `users`: Array of defined users.\n- `resources`: Array of defined resources.\n\n\u003e [!WARNING]  \n\u003e The tool currently does not support templates for the `apiBaseUrl` inside of the `servers` array of the OpenAPI spec.\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eExample of Tool Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n```typescript\nimport { Act, NodeTestRunner, Resource, User } from \"access-control-testing\";\n\nconst users = [user1];\nconst resources = [todoResource];\n\nconst act = new Act({\n  apiBaseUrl: \"http://localhost:3333/\",\n  openApiUrl: \"http://localhost:3333/openapi.yml\",\n  users,\n  resources,\n});\n```\n\n\u003c/details\u003e\n\n---\n\n## Running Tests\n\nOnce all setup steps are completed, you can generate test cases using `generateTestCases()` and run them with a test runner using `.run()`.\n\nTests can be run with any test runner by extending the abstract class `TestRunner`.  \nTo use the built-in Node.js test runner, the adapter `NodeTestRunner` is available (requires Node.js version 18 or higher).\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cstrong\u003eExample of Running Tests\u003c/strong\u003e\u003c/summary\u003e\n\n```typescript\nimport { Act, NodeTestRunner, Resource, User } from \"access-control-testing\";\n\n// Assuming setup steps are completed and `act` instance is configured\nconst testCases = await act.generateTestCases();\nconst testRunner = new NodeTestRunner();\n\nawait testRunner.run(testCases);\n```\n\n\u003c/details\u003e\n\nResults are automatically presented in a clear tabular format in the console.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeerigon%2Faccess-control-testing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeerigon%2Faccess-control-testing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeerigon%2Faccess-control-testing/lists"}