API de perfiles y puntuaciones de seguridad

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Descripción general

En esta página, se describe cómo administrar las puntuaciones de seguridad y los perfiles de seguridad de la evaluación de riesgos (también conocidos simplemente como "perfiles") con las APIs. En esta página, se presentan solicitudes a la API de ejemplo.

Para obtener una descripción general de la funcionalidad de la evaluación de riesgos, incluidas las limitaciones y las instrucciones para usar la IU, consulta Descripción general de la evaluación de riesgos y la IU.

Ejemplos de la API de evaluación de riesgos v2

Parámetros para ejemplos de la API de v2

En los ejemplos de esta sección, se pueden usar los siguientes parámetros:

  • ORG es tu organización.
  • ENV es el entorno en el que deseas que se calculen las puntuaciones.
  • PROFILE_ID es el nombre del perfil. PROFILE_ID puede ser google-default o el nombre de un perfil personalizado que crees.
  • PROFILE_DESC es la descripción del perfil (opcional). Debe ser una descripción del perfil legible por humanos que proporcione suficiente información para diferenciarlo de otros perfiles.
  • PROXY_NAME: El nombre del proxy
  • $TOKEN es la variable de entorno para un token de acceso de OAuth.

Recupera los resultados de la evaluación de seguridad por lotes

Los usuarios con los roles Security Admin o Security Viewer tienen permisos para realizar un cálculo ad hoc de evaluación de riesgos. Deberás especificar el perfil de seguridad, el alcance (el entorno de Apigee) y los recursos que se evaluarán. Los recursos podrían ser include_all_resources: true para calcular en todos los recursos dentro del alcance o solo en algunos. Consulta securityAssessmentResults.batchCompute en la documentación de referencia de la API de administración de Apigee para obtener más información sobre esta funcionalidad.

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityAssessmentResults:batchCompute" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"
  -H 'Content-type: application/json' \
  -d '{
    "profile": "google-default",
    "scope": "ENV",
    "include_all_resources": {}
  }'

Esta es una posible respuesta para la solicitud:

  {
    "security_assessment_results": [
      {
        "resource": {
          "name" : "my-proxy-1",
          "revision": "1"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 99,
        "severity": "low",
        "failed_assessment_by_weight": {
          "MINOR": 1
        },
        "assessment_recommendations": {
          "CORS-Check": {
            "weight": "MINOR",
            "recommendations": [
              {
                "description": "add CORS policy to your proxy",
                "learn_more_link": "https://example.com"
              }
            ]
          }
        }
      },
      {
        "resource": {
          "name" : "my-proxy-2",
          "revision": "3"
        },
        "create_time": "2023-11-22T03:04:05Z",
        "score": 100,
        "severity": "low",
        "resource_revision": "1",
        "failed_assessment_by_weight": {
          "MINOR": 0
        },
        "assessment_recommendations": {}
      }
    ]
  }

Administra perfiles de seguridad

En esta sección, se proporcionan ejemplos para administrar perfiles de seguridad con las APIs, pero no es exhaustiva. Consulta los documentos de referencia de la API de securityProfilesV2 para obtener más información.

Obtén los perfiles de seguridad personalizados existentes

Este comando recupera la información de todos los perfiles de seguridad de tu proyecto:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2" \
      -H "Authorization: Bearer $TOKEN"

Este comando recupera los metadatos de un perfil de seguridad específico y se puede usar para recuperar información sobre el perfil google-default y los perfiles personalizados:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID" \
      -H "Authorization: Bearer $TOKEN"

Crea un perfil de seguridad personalizado nuevo

Para crear un perfil de seguridad personalizado nuevo, usa un comando como el siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2?security_profile_v2_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{
          "description": "PROFILE_DESC",
          "profile_assessment_configs": {
            "auth-policies-check": {"weight": "MINOR"},
            "threat-policies-check": {"weight": "MODERATE"}
          }
       }'
}

Actualiza un perfil de seguridad personalizado existente

Para actualizar un perfil existente, usa un comando como el siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfilesV2/PROFILE_ID?update_mask=UPDATE_MASK" \
       -X PATCH \
       -H "Authorization: Bearer $TOKEN" \
       -H 'Content-type: application/json' \
       -d '{"description": "PROFILE_DESC"}'

En el ejemplo anterior, UPDATE_MASK puede ser uno de estos valores, si está presente: description, profile_assessment_configs, description,profile_assessment_configs o * (todo). Si se especifica la máscara de actualización *, la solicitud actualiza todos los campos, lo que podría quitar valores si no se incluyen en la solicitud.

Si omites update_mask, solo se actualizarán los campos proporcionados en la solicitud de actualización.

Borra un perfil de seguridad personalizado

Borra un perfil de seguridad personalizado:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/securityProfilesV2/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN"

Evaluación de riesgos v1

En esta sección, se muestran información y ejemplos de las APIs de evaluación de riesgos v1.

Limitaciones de las puntuaciones de seguridad cuando se usan las APIs

Las puntuaciones de seguridad tienen las siguientes limitaciones cuando se usan desde las APIs de perfiles y puntuaciones de seguridad:

  • Campos de entrada compatibles en JSON:
  • No se admiten varios filtros de entrada.
  • No se admite el campo de impacto en la respuesta. (El campo de impacto es el posible impacto de esta recomendación en la puntuación general. Esto indica la importancia de esta recomendación para mejorar la puntuación).

Para conocer las limitaciones generales de la puntuación de seguridad no específicas para usar desde las APIs, consulta Limitaciones de las puntuaciones de seguridad v1.

Parámetros en llamadas a la API de ejemplo

En las siguientes secciones, se proporcionan llamadas a la API de ejemplo y se pueden usar los siguientes parámetros:

  • ORG es tu organización.
  • ENV es el entorno en el que deseas que se calculen las puntuaciones.
  • ENVGROUP es un grupo de entornos que contiene el entorno.
  • PROFILE_ID es el nombre del perfil. PROFILE_ID puede ser default o el nombre de un perfil personalizado que crees.

    PROFILE_ID debe contener entre 1 y 63 caracteres, que pueden ser letras minúsculas, números del 0 al 9 o guiones. El primer carácter debe ser una letra minúscula. El último carácter debe ser una letra minúscula o un número.

  • PROXY_NAME: El nombre del proxy
  • RESOURCES puede ser:
    • {"all_resources":true} para todos los recursos dentro del alcance.
    • {"includes": { "resources": [{"name": "<proxy-name>"}]} para supervisar uno o más proxies especificados. Por ejemplo, {"includes": { "resources": [{"name": "my-proxy-1"}]} para supervisar el proxy llamado my-proxy-1.
    • {"excludes": { "resources": [{"name": "<proxy-name>"}]} para supervisar todos los recursos, excepto uno o más proxies especificados. Por ejemplo, {"excludes": { "resources": [{"name": "my-proxy-1"}]} supervisa todos los recursos, excepto el proxy llamado my-proxy-1.
  • $TOKEN es la variable de entorno para un token de acceso de OAuth.
  • timeRange es el intervalo de tiempo de las puntuaciones.

Ejemplos de la API de evaluación de riesgos v1

Filtros compatibles con la API

En la tabla siguiente, se enumeran los filtros compatibles con la API y sus rutas de componentes.

Filtro Ruta de acceso al componente
Puntuaciones del entorno /org@ORG/envgroup@ENVGROUP/env@ENV
La fuente puntúa todos los componentes subyacentes /org@ORG/envgroup@ENVGROUP/env@ENV/source
Puntuaciones de abuso /org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse
Puntuación para todos los proxies /org@ORG/envgroup@ENVGROUP/env@ENV/proxies
Puntuaciones para un proxy específico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME
Puntuación de políticas para un proxy específico
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual
Puntuaciones de la política de mediación para un proxy específico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/mediation
Puntuaciones de la política de seguridad para un proxy específico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security
Puntuaciones de la política de autenticación para un proxy específico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/auth
Puntuación de la política de CORS para un proxy específico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/cors
Puntuaciones de la política de amenazas para un proxy específico /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY_NAME/policies/individual/security/threat
Puntuaciones de políticas para todos los proxies del entorno
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies
  • /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual
Puntuaciones de la política de mediación para todos los proxies del entorno /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/mediation
Puntuaciones de la política de seguridad para todos los proxies del entorno /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security
Puntuaciones de la política de autenticación para todos los proxies del entorno /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/auth
Puntuaciones de la política de CORS para todos los proxies del entorno /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors
Puntuaciones de la política de amenazas para todos los proxies del entorno /org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat

Usa el perfil de seguridad predeterminado

En los siguientes ejemplos, se muestra cómo usar el perfil de seguridad predeterminado. Consulta Parámetros en llamadas de API de ejemplo para ver los parámetros que se usan en los ejemplos.

Conecta el perfil de seguridad predeterminado a un entorno

Para ver las puntuaciones de seguridad, debes adjuntar un perfil al entorno cuya seguridad deseas evaluar. Para conectar el perfil de seguridad predeterminado a un entorno, usa el siguiente comando:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments" \
       -X POST \
       -d '{"name": "ENV"}' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
Obtén la definición de perfil de seguridad predeterminada

Para obtener la definición del perfil de seguridad predeterminado, ingresa el siguiente comando:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default" \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Desconecta el perfil de seguridad predeterminado de un entorno

Si necesitas desconectar el perfil predeterminado de un entorno, puedes hacerlo de la siguiente manera:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/default/environments/ENV" \
         -X DELETE
         -H 'Content-type: application/json' \
         -H "Authorization: Bearer $TOKEN"

Usa un perfil de seguridad personalizado

Puedes crear un perfil de seguridad personalizado con una llamada a la API de cualquiera de las siguientes maneras:

  • Define el perfil de forma explícita en el cuerpo de la llamada.
  • Adjunta un archivo JSON que contenga la definición del perfil a la llamada.

En las siguientes secciones, se proporcionan ejemplos de ambos métodos. Consulta Parámetros en llamadas de API de ejemplo para ver los parámetros que se usan en los ejemplos.

Los siguientes campos en las llamadas a la API de ejemplo especifican el perfil personalizado:

  • description: Una descripción del perfil personalizado.
  • profileConfig: Es una lista de las categorías que se deben incluir en el perfil personalizado. Puede ser cualquier subconjunto de las siguientes categorías de seguridad:
    • abuse
    • authorization
    • cors
    • mtls
    • mediation
    • threat
Define el perfil en el cuerpo de una llamada a la API

Para definir un perfil personalizado en el cuerpo de una llamada a la API, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d '{
         "description":"test custom profile",
         "profileConfig" : {
           "categories":[
             {"cors":{}},
             {"threat":{}}
           ]
         }
       }'

Esto crea un perfil personalizado que incluye las categorías de cors y amenaza, y muestra una respuesta como esta:

{
  "name": "PROFILE_ID",
  "revisionId": "1",
  "revisionCreateTime": "2023-07-17T18:47:08Z",
  "revisionUpdateTime": "2023-07-17T18:47:08Z",
  "scoringConfigs": [
    {
      "title": "json",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/json",
      "description": "Check if JSONThreatProtection policy is configured."
    },
    {
      "title": "xml",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/threat/xml",
      "description": "Check if XMLThreatProtection policy is configured."
    },
    {
      "title": "cors",
      "scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@$proxy/policies/individual/security/cors",
      "description": "Check if CORS policy is configured."
    }
  ],
  "maxScore": 1200,
  "minScore": 200,
  "profileConfig": {
    "categories": [
      {
        "cors": {}
      },
      {
        "threat": {}
      }
    ]
  },
  "description": "test custom profile"
  }
Define el perfil mediante la vinculación de un archivo JSON a una llamada a la API

También puedes definir un perfil de seguridad personalizado si adjuntas un archivo JSON que defina el perfil a una llamada a la API. Por ejemplo, primero crea el siguiente archivo JSON:

{
  "description": "test custom profile",
  "profileConfig" : {
    "categories":[
      {"cors":{}},
      {"threat" :{}},
    ]
  }
}

Esto define un perfil con las categorías de cors y amenaza. Luego, puedes crear un perfil basado en estas categorías de la siguiente manera:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles?security_profile_id=PROFILE_ID" \
       -X POST \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json" \
       -d @create_profile.json

En el ejemplo anterior, create_profile.json es el nombre del archivo JSON descrito anteriormente.

Obtén una definición de perfil de seguridad personalizada

Para obtener la definición de un perfil de seguridad personalizado, ingresa un comando similar al siguiente:

  curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
         -X GET \
         -H "Authorization: Bearer $TOKEN" \
         -H "Content-Type: application/json"
Desconecta un perfil de seguridad personalizado de un entorno

Para desconectar un perfil de seguridad personalizado de un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"
Borra un perfil de seguridad personalizado

Para borrar un perfil de seguridad personalizado, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID" \
       -X DELETE \
       -H "Authorization: Bearer $TOKEN" \
       -H "Content-Type: application/json"

Obtén puntuaciones para un entorno

En las siguientes secciones, se presentan ejemplos de cómo obtener puntuaciones para un entorno. Consulta Parámetros en llamadas de API de ejemplo para ver los parámetros que se usan en los ejemplos.

Obtén todas las puntuaciones de un entorno

Para obtener todas las puntuaciones de un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              }
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

Consulta la página de referencia de computeEnvironmentScores para obtener una descripción de la solicitud y la respuesta.

Obtén puntuaciones de origen para un entorno

Para obtener las puntuaciones de origen de un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
Obtén una puntuación de abuso en la fuente para un entorno

Para obtener la puntuación de abuso en la fuente para un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/source/abuse"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
Obtén puntuaciones para todos los proxies de un entorno

Para obtener puntuaciones de todos los proxies de un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"
Obtén puntuaciones para un proxy específico en un entorno

Para obtener puntuaciones de un proxy específico en un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/proxies/proxy@PROXY"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"

En el ejemplo anterior, PROXY es el proxy cuyas puntuaciones deseas obtener.

Obtén puntuaciones para un destino específico en un entorno

Para obtener puntuaciones para un destino específico en un entorno, ingresa un comando similar al siguiente:

curl "https://apigee.googleapis.com/v1/organizations/ORG/securityProfiles/PROFILE_ID/environments/ENV:computeEnvironmentScores" \
       -X POST \
       -d '{"timeRange":
              {
                "startTime": "YYYY-MM-DDT00:00:00Z",
                "endTime": "YYYY-MM-DDT00:00:00Z"
              },
            "filters": [{"scorePath": "/org@ORG/envgroup@ENVGROUP/env@ENV/target@TARGET"}]
           }' \
       -H 'Content-type: application/json' \
       -H "Authorization: Bearer $TOKEN"