ado_enum.py

#!/usr/bin/env python3

import sys
import argparse
from utils.client import ADOError
from utils import (
    projects,
    repos,
    service_endpoints,
    builds,
    build_logs,
    search_code,
    enumerate as enum_module,
    build_artifacts,
    whoami,
    pipeline_secrets,
    variable_groups,
    secure_files,
    approvals_checks,
    branch_policies,
    permissions,
)


def build_arg_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="ado-enum",
        description="Azure DevOps enumeration tool — projects, repositories, service connections, and more.",
    )
    parser.add_argument("--org", required=True, help="Azure DevOps organisation name (e.g. myorg)")
    parser.add_argument(
        "--pat",
        help="Personal Access Token. If omitted, reads AZURE_DEVOPS_PAT or ADO_PAT environment variable.",
    )
    parser.add_argument(
        "-k",
        "--insecure",
        action="store_true",
        help="Disable TLS verification (useful with intercepting proxies).",
    )

    sub = parser.add_subparsers(dest="command", required=True)

    # projects
    p_proj = sub.add_parser("projects", help="List projects in the organisation.")
    p_proj.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_proj.set_defaults(func=projects.cmd_projects)

    # repositories
    p_repo = sub.add_parser("repos", help="List git repositories in the organisation.")
    p_repo.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_repo.set_defaults(func=repos.cmd_repos)

    # service endpoints
    p_se = sub.add_parser("service-endpoints", help="Enumerate service connections.")
    p_se.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_se.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_se.set_defaults(func=service_endpoints.cmd_service_endpoints)

    # builds
    p_builds = sub.add_parser("builds", help="List builds for projects.")
    p_builds.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_builds.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_builds.set_defaults(func=builds.cmd_builds)

    # build-logs
    p_build_logs = sub.add_parser("build-logs", help="Download build logs.")
    p_build_logs.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_build_logs.add_argument(
        "--build-id", type=int, help="Download logs for a specific build ID (requires --project)."
    )
    p_build_logs.add_argument(
        "--output-dir", default="build_logs", help="Directory to save log files (default: build_logs)."
    )
    p_build_logs.set_defaults(func=build_logs.cmd_build_logs)

    # search-code
    p_search = sub.add_parser("search-code", help="Search for code across repositories.")
    p_search.add_argument("search_text", help="Text to search for.")
    p_search.set_defaults(func=search_code.cmd_search_code)

    # enumerate
    p_enum = sub.add_parser(
        "enumerate",
        help="Enumerate current logged in user, repos, service connections, and projects.",
    )
    p_enum.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_enum.set_defaults(func=enum_module.cmd_enumerate)

    # permissions
    p_perms = sub.add_parser(
        "permissions",
        help="List groups, security namespaces, and ACL permissions.",
    )
    p_perms.add_argument("--project", help="Limit group listing to a specific project.")
    p_perms.add_argument(
        "--org-level",
        action="store_true",
        help="List org-level groups only instead of all project groups.",
    )
    p_perms.add_argument(
        "--user",
        metavar="USER",
        help="Show groups and permissions for a specific user (email or display name).",
    )
    p_perms.add_argument(
        "--group",
        metavar="GROUP",
        help="Show permissions for a specific group (display name or principal name).",
    )
    p_perms.set_defaults(func=permissions.cmd_permissions)

    # whoami
    p_whoami = sub.add_parser(
        "whoami",
        help="Identify the authenticated user and list their group memberships.",
    )
    p_whoami.set_defaults(func=whoami.cmd_whoami)

    # pipeline-vars
    p_vars = sub.add_parser("pipeline-vars", help="List all variables defined in build pipelines.")
    p_vars.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_vars.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_vars.set_defaults(func=pipeline_secrets.cmd_pipeline_vars)

    # pipeline-secrets
    p_secrets = sub.add_parser("pipeline-secrets", help="List secret variable names defined in build pipelines.")
    p_secrets.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_secrets.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_secrets.set_defaults(func=pipeline_secrets.cmd_pipeline_secrets)

    # variable-groups
    p_vg = sub.add_parser("variable-groups", help="List variables defined in variable groups.")
    p_vg.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_vg.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_vg.set_defaults(func=variable_groups.cmd_variable_groups)

    # secure-files
    p_sf = sub.add_parser("secure-files", help="List secure files registered in projects.")
    p_sf.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_sf.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_sf.set_defaults(func=secure_files.cmd_secure_files)

    # approvals-checks
    p_ac = sub.add_parser(
        "approvals-checks",
        help="Enumerate approvals and checks for protected pipeline resources.",
    )
    p_ac.add_argument(
        "resource_type",
        nargs="?",
        choices=approvals_checks.RESOURCE_TYPES,
        metavar="RESOURCE_TYPE",
        help=(
            "Resource type to enumerate. One of: "
            + ", ".join(approvals_checks.RESOURCE_TYPES)
            + ". Defaults to all types."
        ),
    )
    p_ac.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_ac.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_ac.set_defaults(func=approvals_checks.cmd_approvals_checks)

    # branch-policies
    p_bp = sub.add_parser("branch-policies", help="Enumerate branch policies for a repository.")
    p_bp.add_argument("--project", required=True, help="Project name.")
    p_bp.add_argument("--repository", required=True, help="Repository name or ID.")
    p_bp.add_argument(
        "--branch",
        help="Branch to filter by (e.g. main or refs/heads/main). Defaults to all branches.",
    )
    p_bp.add_argument("--json", action="store_true", help="Output raw JSON.")
    p_bp.set_defaults(func=branch_policies.cmd_branch_policies)

    # build-artifacts
    p_artifacts = sub.add_parser("build-artifacts", help="List and download build artifacts.")
    p_artifacts.add_argument("--project", help="Limit to a single project. Defaults to all projects.")
    p_artifacts.add_argument(
        "--build-id", type=int, help="Limit to a specific build ID (requires --project)."
    )
    p_artifacts.add_argument("--download", action="store_true", help="Download artifacts.")
    p_artifacts.add_argument("--artifact-name", help="Download a specific artifact by name.")
    p_artifacts.add_argument(
        "--output-dir", default="build_artifacts", help="Directory to save artifacts (default: build_artifacts)."
    )
    p_artifacts.set_defaults(func=build_artifacts.cmd_build_artifacts)

    return parser


def main() -> None:
    parser = build_arg_parser()
    args = parser.parse_args()
    try:
        args.func(args)
    except ADOError as e:
        print(str(e), file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()