Project

A Project is a continuous security entity within an organization. While an Assessment is a single scan run, a Project represents an ongoing relationship with a specific codebase or target. It owns a source (connected repositories, one public URL, or an archive series), can enable PR review, scheduled scans, and monitoring, and maintains a living knowledge base that makes each subsequent assessment faster and more accurate.

Restoring an archived project also restores the assessments archived with it. The project accepts new runs after restoration finishes. If restoration fails, retry Unarchive; the project stays archived until the remaining work succeeds.

Creating one

You set up everything a project holds on one screen: its name and description, who on your team can see it, its source and file scope, and the targets and credentials an assessment needs to reach the running system. AISafe saves the whole project in one step, so if any part is refused, nothing is left half-created.

Only the name is required. You can create a project with no source and no targets, and add either later. AISafe checks what each kind of assessment needs when you start an assessment of that kind:

To run	The project needs
A free scan or a code audit	a source — connected repositories, a public repository URL, or an uploaded archive
A black-box assessment	at least one target URL
A white-box assessment	a source and at least one target URL
PR review	a connected GitHub or GitLab repository. An anonymous public URL cannot receive webhooks, and Bitbucket pull requests are not reviewed yet

Rules of engagement, per-assessment instructions, scheduled scans, PR review and monitoring are configured on the project after it exists, from its own tabs.

If you only want to look at some code, the dashboard has a shortcut: press Start a free scan (Create project & scan on a brand-new dashboard), pick the repository, and the project is created and scanned in place.

Source

A project connects several repositories from GitHub, GitLab, or Bitbucket: up to five on the Free and Pro plans, and as many as you need on Enterprise. Each has its own branch and file scope, and they may use different authorized connections in the same workspace. Connected public repositories are supported too. Pick them all from the same provider: one project does not mix GitHub with GitLab.

If your application is more than five repositories, write to sales@aisafe.io about an Enterprise plan.

AISafe resolves every repository to an exact commit and scans the combined source as one application. The source size limits and pricing apply to the combined source. A scan produces one assessment and report. Each repository occupies its own directory beneath the source root, such as web/src/main.ts and api/src/main.ts.

A directory is named after the repository. When two repositories would take the same name, the second gets a number: api/ and api-2/. A directory is assigned once and kept, so adding or removing a repository never moves the paths you have already read. Renaming a repository upstream preserves its source directory and historical evidence paths; new snapshots record the current upstream name. A rename does not reset living knowledge. Moving a repository between owners still requires the connection to retain access to that exact repository.

An anonymous public URL and an uploaded archive remain single-source alternatives. The project keeps a revision history with named refs, so an assessment can use a recorded complete application revision. Each revision records every repository's exact commit. Historical single-repository revisions retain their original paths.

Creating a project from connected repositories fetches their branches straight away, so the project opens with its first revision already recorded. A project created together with a first scan gets its first revision when the scan starts.

Changing a repository's branch in Setup → Source and saving the repositories updates the default project ref and fetches that branch, so a new revision is recorded without a separate Sync now. Attaching repositories to a project that has none yet does the same: Save repositories fetches and records the first revision. Other named refs keep their branches, and past revisions stay unchanged. Clearing the branch tracks the repository's default branch.

Sync now pulls the latest commits for the saved branches of the tracked ref. While you have an unsaved branch or path change, the button stays off until you save it, because a sync would read the old branch. A large source takes minutes to fetch, so the button responds at once, and the page shows the result under Source history when the fetch finishes: either the new revision or a confirmation that nothing changed. If you press the button again while a sync is running, AISafe follows the running sync instead of starting another.

Add or remove connected repositories only when you first connect source. After that, the kind of source and the set of repositories in it stay fixed. Change a branch or path scope in Setup → Source, use Sync now, or upload a new archive. Start a new project to connect different repositories. An anonymous public URL cannot become an authorized GitHub, GitLab, or Bitbucket connection, even for the same owner and repository.

A pending change that was made before this freeze still shows a retry action until it completes. New scans and reviews stay paused until then.

AISafe checks access to every repository before accepting a source. A repository that cannot be read must be repaired or removed from the selection before the combined scan starts.

Updating project source through the API

POST /api/v1/projects/{id}/revisions/upload (an archive), POST /api/v1/projects/{id}/revisions/patch (a unified diff against one project revision, base_revision_id) and POST /api/v1/projects/{id}/revisions (fetch the connected repositories) answer 202 Accepted with an attachment whose status is running, and a worker adds the revision. Poll GET /api/v1/projects/{id}/revision-attachments/{attachment_id} every few seconds until status is succeeded or failed:

• succeeded carries outcome (created, or unchanged when the source already matched the ref) and project_revision, whose parent_revision_id is the revision it follows.
• failed carries error.code, error.message and error.retryable.

A project takes changes only from its own source. A project connected to repositories (or to a public repository URL) takes them from those repositories: push the change there and sync the project. An upload or a patch to such a project is refused with 400 project_source_is_repository, and the message names the repositories. Only a project whose source is an uploaded archive takes uploads and patches.

An uploaded archive is always the project's whole codebase. The new revision holds the archive's files, with the project's scope applied, and nothing of the previous revision, so a file that is not in the archive is not in the new revision. To change some of the code, upload an archive of the whole codebase with the change in it, or send a patch. An archive cannot be placed in one folder of the project: a request that names target_path is refused with 400 project_upload_target_path_unsupported.

Each update goes on ref_name, or on the project's default ref when you leave it out. A patch must be made against the ref's current revision; one made against an older revision fails with project_patch_base_stale. The idempotency_key rules are those of updating an assessment's source: the same key and request return the same attachment, and a failed attempt needs a new key. While one update runs, a second one for the same project is refused with 409 source_activity_in_flight.

An archive of any size your plan allows can also go up in parts, which survives a dropped connection: follow uploading an archive of any size with the target {"kind": "project_revision", "project_id": "PROJ-...", "ref_name": "main"} (ref_name is optional). The CLI does the same with aisafe upload <archive> --project PROJ-... [--ref main].

Scope

Choose files and directories independently for each repository when you create the project or edit its scope in Setup. Connected repositories, public URLs, and uploaded source use the same default exclusions: images, build output, and vendored files are unchecked when the picker opens. Use Include excluded or check a file to include it. Saved selections keep these choices when you reopen the picker. Select at least one file before saving a repository's scope.

Each tree shows the size of its selected files. For multiple repositories, All repositories shows their combined size against the source limit. These sizes count files before compression; the price estimate counts only code the analyzer can parse.

When exclusions or your choices narrow the scope, AISafe saves the selected paths. Review that scope when adding files you want covered. A full selection with no default exclusions covers the whole repository, including future files.

The scope is part of the project, so every assessment, scheduled scan and PR review on it reads the same set of files. You can change it at any time from the project's Setup tab; the new scope applies to the next revision, and past revisions keep the scope they were tested with.

Continuous capabilities

A project can enable three continuous capabilities, each independent of individual assessments:

PR Review

Configure PR reviews separately for each connected GitHub or GitLab repository. Within a workspace, exactly one selected project reviews a repository. If another project already owns the selection, release it there before selecting this project. Each workspace runs and pays for its own review. For a PR in one repository, AISafe holds its companion repositories at identical commits while comparing the PR's base and head. Comments and checks identify the workspace and project; companion source evidence stays behind AISafe access controls. See Pull Request Review.

For VCS-backed projects, the Source tab includes a webhook delivery log. It shows recent push and pull-request events, whether AISafe processed or ignored them, and the reason when ignored.

Scheduled Scans

You can configure recurring scan cadences (e.g. each day, each week, each month). When a scheduled scan is due, AISafe creates a normal assessment for it. See Scheduled scans.

Monitoring

Monitoring re-validates finding proof-of-concepts and alerts you when a fix regresses or a safe area becomes vulnerable. See Endpoint Monitoring.

Deleting a project

When you delete a project, AISafe stops all of the project's future work and keeps the record of the work it has already done.

While a run is live: if an assessment, a PR review or a monitoring run is still executing against the project, AISafe refuses the delete and tells you which runs are blocking it. Wait for those runs to finish, or stop them, and then delete the project again. A run that has finished never blocks a delete.

What goes: the project itself, every copy of the source code AISafe holds for it, its schedules and monitoring configuration, and its project-scoped suppressions, webhooks, notification targets and issue-export targets.

What stays: the work you paid for. Assessments keep their findings and reports and become standalone assessments, exactly as if they had never been attached to a project. You can still open PR reviews and monitoring runs by their own codes (PR-…, MON-…), so a finding that cites a run still links to something you can open. Only their source code is deleted.

The deleted project's PROJ-… id is never assigned to another project in your organization. Kept findings, reviews and monitoring runs may still cite it, so reusing the id would make unrelated history appear under a new project.

Living knowledge base

Each project owns a living knowledge base: a persistent store that accumulates context across scans. A project-bound assessment loads prior findings, code structure understanding, and triage decisions from this knowledge base at start. An assessment of the Project's default version saves new knowledge back at completion. An assessment-local source update changes one selected repository and preserves every companion at the commits recorded in that assessment. It does not change the project or its living knowledge. Your second default-version scan of a repo is faster and more accurate than the first.

Project-bound vs standalone assessments

Assessments may belong to a project. Project-bound code audits take their source from the project. You choose the complete application revision/ref; each repository inherits its configured path scope. Project-bound pentests inherit the project's blackbox configuration as defaults. Standalone assessments (not bound to any project) retain their existing behavior, with no knowledge base loading.