Spring Boot Actuator: expose only needed endpoints, restrict access, and verify configuration

Spring Boot Actuator: What to Expose, What to Hide, and What to Check Before Adding Endpoints

Spring Boot Actuator: What to Expose, What to Hide, and What to Check Before Adding Endpoints There's a configuration that shows up in almost every Spring Boot tutorial, and people copy it without really reading it: management: endpoints: web: exposure: include: "*" One asterisk. Every endpoint. All at once. And the tutorial moves straight to the next step without pausing for even a second to think about what that actually means. My take is simple: Actuator isn't bad. The mistake is enabling it without a clear policy for what to expose, what to restrict, and for whom. That gap between operational tool and unnecessary public surface area isn't something Spring Boot closes on its own — you close it with explicit judgment. I've been in tech for over thirty years, and one of the patterns I keep seeing isn't the dramatic bug that takes down production: it's the small decision made without a policy, accumulating quietly until someone finds it from the outside. Spring Boot Actuator Endpoints Security: What the Docs Say — and What They Don't The official Spring Boot Actuator documentation is clear about something most tutorials skip: by default, only health and info are exposed over HTTP. The rest exist but aren't automatically accessible. What the documentation spells out precisely: The distinction between enabling an endpoint (it exists in the context) and exposing it (it's reachable via HTTP or JMX). That shutdown is enabled but not exposed by default — precisely because its impact is irreversible. That env and configprops can leak sensitive values, and that Spring Boot offers configurable sanitization for those cases. That securing endpoints is the developer's responsibility: Spring Boot doesn't add automatic authentication over Actuator. What the documentation doesn't resolve for you: Which endpoints actually make sense for your specific operation. Whether the management port is separated from the app port or shared. Whether there's a proxy, API gateway, or load balancer in front that filters — or doesn't filter — those routes. Whether the team operating the system has differentiated access from public traffic. That gap between "what Spring Boot configures by default" and "what you need in production" is exactly where implicit decisions pile up. The Most Common Mistake: Enable Everything and Secure It Later (or Never) The recipe that circulates across tutorials, Stack Overflow, and example repos usually looks like this: # application.yml — common pattern worth reviewing before copying management: endpoints: web: exposure: include: "*" endpoint: health: show-details: always The hidden cost of this pattern isn't that it's "dangerous" in the abstract. The concrete cost is: /actuator/env exposes environment variables — including keys, database URLs, and tokens if they aren't sanitized. /actuator/heapdump can return a full JVM heap dump, which in many systems contains live in-memory data. /actuator/shutdown lets you kill the application via HTTP POST if it's enabled and exposed. /actuator/loggers lets you change log levels at runtime, which can generate operational noise or expose diagnostic information. None of those endpoints are inherently bad. heapdump is invaluable for diagnosing a memory leak. loggers is exactly the tool you want when you need DEBUG output without a restart. The problem is exposing them without deciding who can reach them and from where. The analogy I keep coming back to: it's similar to what happens with Docker healthchecks. A badly designed healthcheck doesn't fail because Docker is broken — it fails because nobody defined what "healthy" actually means for that container. Actuator is the same story: the tool is solid, but the exposure criteria has to be explicit. Decision Matrix: What to Expose, What to Restrict, What to Disable Entirely This matrix is a pragmatic guide, not an absolute rule. Each row represents an analysis worth doing before including that endpoint. Endpoint What it exposes Recommended approach health App state and dependency health Expose. Use show-details: when-authorized in production info Build metadata, version, git commit Expose if you have useful data. Nothing sensitive by default metrics JVM, HTTP, and custom metrics Expose only to internal monitoring systems (Prometheus, etc.) loggers Current logging levels Restrict to operators. Useful, but with controlled access env Environment variables Restrict. Review sanitization before enabling configprops Configuration properties Restrict. Can surface sensitive values heapdump JVM heap dump Controlled environments only. Not on public production threaddump Active thread state Useful for diagnostics. Restrict to operators shutdown Shuts down the application Don't enable unless there's a very clear operational reason mappings All REST endpoints in the app Surface area information. Restrict beans All Spring context beans Development only. Not in production The configuration I'd use as a starting point in a production environment: # application.yml — pragmatic starting point for production management: server: port: 8081 # separate port, not publicly exposed endpoints: web: exposure: include: health, info, metrics, loggers endpoint: health: show-details: when-authorized env: enabled: false # disable if no sanitization policy is defined Separating the management port (management.server.port) from the application port is a decision that dramatically simplifies your policy: internal traffic hits 8081, public traffic has no access to that port at all. It turns security into a structural property instead of something that depends entirely on getting every auth rule right in code. What You Can't Conclude Without Your Own Experiments, Logs, or Data There's an honest limit worth naming here. This guide is based on the official documentation and careful analysis. What you can't conclude from this alone: That your current configuration is secure: that requires checking what's in front of your app (proxy, gateway, firewall) and how it's configured. That separating the management port is sufficient: if port 8081 is open in your security group or network firewall, the separation means nothing. That env sanitization covers all your sensitive keys: Spring Boot sanitizes by known patterns (password, secret, key, etc.), but if you're using unconventional variable names, verify it explicitly. That adding Spring Security over Actuator is the only solution: you can also handle access at the network level, proxy level, or ingress level. The right layer depends on your architecture. If you want to inspect what traffic is actually reaching your management endpoints in a local environment, a tool like Sniffnet can help you visualize connections without diving straight into tcpdump. FAQ: Spring Boot Actuator Endpoints Security Which Actuator endpoints are enabled by default? According to the official documentation, only health and info are exposed over HTTP by default. The rest are enabled in the context but not reachable via HTTP. The exception is shutdown, which isn't enabled by default precisely because of its impact. What's the difference between enabling and exposing an endpoint? Enabling means the endpoint exists in the Spring context and can be invoked internally. Exposing means it's reachable from outside (HTTP or JMX). You can have an endpoint enabled but not exposed: it exists, but nothing can call it from the outside. The management.endpoints.web.exposure.include property controls HTTP exposure. Is Spring Security enough to protect Actuator? Spring Security is a valid layer, but it's not the only one — and it's not necessarily your first line of defense. Separating the management port and restricting access to it at the network or proxy level is a more robust policy because it doesn't depend on every security rule in your code being correct. Ideally, both layers coexist. Does /actuator/health expose sensitive information? With the default configuration, health returns only the status (UP or DOWN). Dependency details (database, disk, etc.) only appear if you configure show-details: always. The more sensible middle ground for production is show-details: when-authorized: your monitoring system sees the detail, anonymous traffic doesn't. What happens if I use include: "*" in production? Every enabled endpoint gets exposed — including env, configprops, heapdump, and potentially shutdown if you've enabled it. It's not an invalid configuration in every context, but it requires that access to the management port be completely restricted to internal systems. If that port is publicly reachable, anyone can query your environment variables or request a heap dump. How do I validate which endpoints are actually exposed in my app? The /actuator endpoint returns a JSON with active endpoints and their URLs. That's your first stop. You can also check Spring Boot's startup logs: it logs registered endpoints at the right log level. And if you have Prometheus or any scraping system configured, verify it's only hitting the management port — not the public one. My Take: Actuator Is an Operational Tool, Not a Convenience Feature When I first encountered the Docker healthcheck story I mentioned in that earlier post, what stuck with me was the same lesson that applies here: the value of a tool is in describing an explicit contract, not in turning it on and seeing what happens. Actuator is the same. It's not a feature you "add" to the app. It's an observability policy that defines what operational information gets exposed, to whom, and from where. That policy can be as simple as two lines in your YAML or as elaborate as differentiated roles with Spring Security — but it has to exist consciously. The uncomfortable part is that the tutorial everyone copies shows include: "*" as if it were the natural next step. And technically it works. But "it works" and "it's a decision made with judgment" are different things, and that difference matters when the system grows. The practical move for right now: open the application.yml of whatever project you're working on, find the management.endpoints section, and ask yourself whether what's there is an explicit policy or the result of copying a tutorial without questioning it. If it's the second thing, spend fifteen minutes on it before the system goes to a shared environment. Not because Actuator is dangerous. But because implicit decisions are the ones that accumulate. Sources: Spring Boot Actuator — Endpoints (official documentation) This article was originally published on juanchi.dev

2 hours ago

Spring Boot Actuator: qué exponer, qué ocultar y qué mirar antes de agregar endpoints

Spring Boot Actuator: qué exponer, qué ocultar y qué mirar antes de agregar endpoints Hay una configuración que aparece en casi todos los tutoriales de Spring Boot y que se copia sin leerla bien: management: endpoints: web: exposure: include: "*" Un asterisco. Todos los endpoints. De una. Y el tutorial sigue con el paso siguiente sin detenerse un segundo en lo que eso significa. Mi tesis es simple: Actuator no es malo. El error es habilitarlo sin una política clara de qué exponer, qué restringir y para quién. Esa diferencia entre herramienta operativa y superficie pública innecesaria no la resuelve Spring Boot solo: la resolvés vos con criterio explícito. Tengo más de treinta años de historia con la tecnología, y uno de los patrones que más veo repetirse no es el bug dramático que tira producción: es la decisión pequeña tomada sin política, que se acumula hasta que alguien la encuentra desde afuera. Spring Boot Actuator endpoints seguridad: qué dice la documentación y qué no dice La documentación oficial de Spring Boot Actuator es clara en algo que los tutoriales suelen saltear: por defecto, sobre HTTP solo están habilitados health e info. El resto existe pero no se expone automáticamente. Lo que la documentación describe con precisión: La distinción entre habilitar un endpoint (que exista en el contexto) y exponerlo (que sea accesible por HTTP o JMX). Que shutdown está habilitado pero no expuesto por defecto, precisamente porque su impacto es irreversible. Que env y configprops pueden mostrar valores sensibles, y que Spring Boot ofrece sanitización configurable para esos casos. Que la seguridad de los endpoints es responsabilidad del desarrollador: Spring Boot no agrega autenticación automática sobre Actuator. Lo que la documentación no resuelve por vos: Qué endpoints tienen sentido para vos operación concreta. Si el puerto de management está separado del puerto de la app o compartido. Si hay un proxy, API gateway o balanceador de carga delante que filtra o no esas rutas. Si el equipo que opera el sistema tiene acceso diferenciado del tráfico público. Esa brecha entre "lo que Spring Boot configura por defecto" y "lo que necesitás en producción" es exactamente donde se acumulan las decisiones implícitas. El error más común: habilitar todo y securizar después (o nunca) La receta que circula en tutoriales, Stack Overflow y repositorios de ejemplo suele tener esta forma: # application.yml — patrón común que vale revisar antes de copiar management: endpoints: web: exposure: include: "*" endpoint: health: show-details: always El costo oculto de este patrón no es que "sea peligroso" en abstracto. El costo concreto es que: /actuator/env expone variables de entorno, incluyendo claves, URLs de base de datos y tokens si no están sanitizadas. /actuator/heapdump puede devolver un dump del heap de la JVM, que en muchos sistemas contiene datos en memoria. /actuator/shutdown permite apagar la aplicación vía HTTP POST si está habilitado y expuesto. /actuator/loggers permite cambiar el nivel de logging en caliente, lo que puede generar ruido operativo o exponer información de diagnóstico. Ninguno de esos endpoints es malo en sí mismo. heapdump es invaluable para diagnosticar un leak de memoria. loggers es exactamente la herramienta que querés cuando necesitás DEBUG sin reiniciar. El problema es exponerlos sin decidir quién puede acceder y desde dónde. La comparación que me resulta útil: es parecido a lo que pasa con los Docker healthchecks. Un healthcheck mal diseñado no falla porque Docker sea malo; falla porque nadie definió qué significa "sano" para ese contenedor en particular. Con Actuator pasa lo mismo: la herramienta es sólida, pero el criterio de exposición tiene que ser explícito. Matriz de decisión: qué exponer, qué restringir, qué directamente no habilitar Esta matriz es un criterio prudente, no una regla absoluta. Cada fila representa un análisis que vale hacer antes de incluir ese endpoint. Endpoint ¿Qué expone? Criterio recomendado health Estado de la app y sus dependencias Exponer. show-details: when-authorized en producción info Metadata de build, versión, git commit Exponer si hay datos útiles. No expone nada sensible por defecto metrics Métricas JVM, HTTP, custom Exponer solo a sistemas de monitoreo internos (Prometheus, etc.) loggers Niveles de logging actuales Restringir a operadores. Útil, pero con acceso controlado env Variables de entorno Restringir. Revisar sanitización antes de habilitar configprops Propiedades de configuración Restringir. Puede mostrar valores sensibles heapdump Dump del heap de la JVM Solo en ambientes controlados. No en producción pública threaddump Estado de los threads activos Útil para diagnóstico. Restringir a operadores shutdown Apaga la aplicación No habilitar salvo que haya una razón operativa muy clara mappings Todos los endpoints REST de la app Información de superficie. Restringir beans Todos los beans del contexto Spring Solo en desarrollo. No en producción La configuración que yo usaría como punto de partida en un ambiente productivo: # application.yml — punto de partida prudente para producción management: server: port: 8081 # puerto separado, no expuesto públicamente endpoints: web: exposure: include: health, info, metrics, loggers endpoint: health: show-details: when-authorized env: enabled: false # deshabilitar si no hay política de sanitización definida Separar el puerto de management (management.server.port) del puerto de la aplicación es una decisión que simplifica mucho la política: el tráfico interno llega al 8081, el tráfico público no tiene acceso a ese puerto en absoluto. Es una forma de convertir la seguridad en una propiedad estructural en lugar de depender solo de autenticación. Lo que no podés concluir sin experimento, logs o datos propios Hay un límite honesto que vale nombrar. Esta guía está basada en la documentación oficial y en análisis prudente. Lo que no podés concluir solo con esto: Que vos configuración actual es segura: eso requiere revisar qué hay delante de la aplicación (proxy, gateway, firewall) y cómo está configurado. Que separar el puerto de management es suficiente: si el puerto 8081 está expuesto en el security group o en el firewall de red, la separación no sirve. Que la sanitización de env cubre todas las claves sensibles: Spring Boot sanitiza por patrones conocidos (password, secret, key, etc.), pero si usás nombres de variables no convencionales, vale verificarlo. Que agregar Spring Security sobre Actuator es la única solución: también podés resolver el acceso a nivel de red, de proxy o de ingress. La capa correcta depende de la arquitectura. Si querés inspeccionar qué tráfico llega realmente a los endpoints de management en un ambiente local, una herramienta como Sniffnet puede ayudarte a visualizar conexiones sin meterte en tcpdump desde el primer momento. FAQ: Spring Boot Actuator endpoints seguridad ¿Cuáles son los endpoints de Actuator que están habilitados por defecto? Según la documentación oficial, sobre HTTP solo health e info están expuestos por defecto. El resto están habilitados en el contexto pero no accesibles por HTTP. La excepción es shutdown, que no está habilitado por defecto justamente por su impacto. ¿Qué diferencia hay entre habilitar y exponer un endpoint? Habilitar significa que el endpoint existe en el contexto de Spring y puede ser invocado internamente. Exponer significa que es accesible desde el exterior (HTTP o JMX). Podés tener un endpoint habilitado y no expuesto: existe pero nadie puede llamarlo desde fuera. La propiedad management.endpoints.web.exposure.include controla la exposición HTTP. ¿Es suficiente con Spring Security para proteger Actuator? Spring Security es una capa válida, pero no es la única ni necesariamente la primera línea. Separar el puerto de management y restringir acceso a ese puerto a nivel de red o proxy es una política más robusta porque no depende de la correcta configuración de cada regla de seguridad en el código. Idealmente, ambas capas conviven. ¿/actuator/health expone información sensible? Con la configuración por defecto, health devuelve solo el estado (UP o DOWN). El detalle de dependencias (base de datos, disco, etc.) aparece solo si configurás show-details: always. La opción intermedia y más razonable en producción es show-details: when-authorized: el sistema de monitoreo ve el detalle, el tráfico anónimo no. ¿Qué pasa si uso include: "*" en producción? Se exponen todos los endpoints habilitados, incluyendo env, configprops, heapdump y potencialmente shutdown si lo habilitaste. No es una configuración inválida en todos los contextos, pero requiere que el acceso al puerto de management esté completamente restringido a sistemas internos. Si ese puerto es accesible públicamente, cualquiera puede consultar variables de entorno o pedir un dump del heap. ¿Cómo valido qué endpoints están realmente expuestos en mi app? El endpoint /actuator devuelve un JSON con los endpoints activos y sus URLs. Es el primer lugar donde mirar. También podés revisar los logs de startup de Spring Boot: loguea los endpoints registrados si tenés el nivel adecuado. Y si tenés Prometheus o cualquier sistema de scraping configurado, verificá que solo raspe el puerto de management y no el puerto público. Mi postura: Actuator es una herramienta operativa, no una opción de conveniencia Cuando vi por primera vez la anécdota de Docker que mencioné al principio del post sobre healthchecks, lo que me quedó fue la misma lección que aplica acá: el valor de la herramienta está en describir un contrato explícito, no en activarla y ver qué pasa. Con Actuator es igual. No es una feature que "agregás" a la app. Es una política de observabilidad que define qué información operativa se expone, a quién y desde dónde. Esa política puede ser tan simple como dos líneas en el YAML o tan elaborada como roles diferenciados con Spring Security, pero tiene que existir de forma consciente. Lo incómodo es que el tutorial que más circula muestra el include: "*" como si fuera el paso natural. Y técnicamente funciona. Pero "funciona" y "es una decisión tomada con criterio" son cosas distintas, y la diferencia importa cuando el sistema crece. La decisión práctica para el próximo paso es esta: abrí el application.yml del proyecto en el que estás trabajando ahora, buscá la sección management.endpoints, y preguntate si lo que está ahí es una política explícita o el resultado de copiar un tutorial sin cuestionarlo. Si es lo segundo, dedicale quince minutos antes de que el sistema salga a un ambiente compartido. No porque Actuator sea peligroso. Sino porque las decisiones implícitas son las que se acumulan. Fuentes: Spring Boot Actuator — Endpoints (documentación oficial) Este artículo fue publicado originalmente en juanchi.dev

2 hours ago